The pixel coordinates specified by (X1,Y1) to (X2,Y2) define
the outer bounding-box edge that surrounds or defines the shape of
the 3D object or component.
Draw a 3-D box, button, embossed, inset, or raised panel, or 3D beveled frame in graphic mode
Syntax:
nStatus = Draw3DBox(<nFaceWidth>, <nOuterBevelWidth>, <nInnerBevelWidth>,
<nLightColor>, <nShadowColor>, <nFaceColor>, <nX1>,
<nY1>, <nX2>, <nY2>);
Parameters
nFaceWidth Box face width in pixels.
Can specify a border or rim or an entire
flat surface. Can be set to 0 for an
embossed or raise surrounding line
effect in the shape of a box.
nOuterBevelWidth The width in pixels for the outer
beveled surface. Usually non-zero.
Suggested range 1 - 4 pixels depending
on design and video mode.
nInnerBevelWidth The width in pixels for the inner
beveled surface. Can be zero or non-zero.
Suggested range 0 - 4 pixels depending
on design and video mode.
nLightColor The color index for the beveled surfaces
facing toward the light source (for the
raised portion of the design). Can be
referred to as the highlighted surface.
Suggested color: bright white. Can be
swapped with nShadowColor for an inset effect.
nLightColor = 15 for raised effect or
nLightColor = 8 for inset effect
nShadowColor The color index for the beveled surfaces
facing away from the light source (for
the inset portion of the design). Can be
referred to as the shadowed surface.
Suggested colors: dark grey or black.
Can be swapped with nShadowColor for an
inset effect.
nShadowColor = 8 for raised effect or
nShadowColor = 15 for inset effect
nFaceColor The color index for the flat surface
facing the on-looker, upon which additional
design elements or buttons may be placed.
Suggested color should be a neutral color
such as 7 or white.
nX1 Left coordinate of 3D box to draw.
nY1 Top coordinate of 3D box to draw.
nX2 Right coordinate of 3D box to draw.
nY2 Bottom coordinate of 3D box to draw.
Returns
-1 Draw3DBox can only draw in graphic modes
-2 Can not allocate memory for line buffer
-99 Parameters are invalid
Draw a 3D beveled box specified by (nX1, nY1), (nX2, nY2), where width is nFaceWidth, where outer bevel width is nOuterBevelWidth, where the inner bevel width is nInnerBevelWidth and where colors are specified by nLightColor, nShadowColor, nFaceColor. Draw3DBox() is an important, useful function for graphical interface design with many options. Refer to the example for many suggestions.
Design elements of the user interface are crucial for an application's understandability, clarity and ease of use. Designing a graphic mode interface allows many more design options, elements, can have better organization and structure than a textmode interface. Graphical interfaces have been proven in studies to contribute to easier usage & understanding of computer programs, especially by the new user. The modern, 3D panel, button or frame as typified by Draw3DBox() is usually composed of the following components:
The pixel coordinates specified by (X1,Y1) to (X2,Y2) define
the outer bounding-box edge that surrounds or defines the shape of
the 3D object or component.
The OuterBevelWidth specifies an outer beveled edge to the
panel, button or frame. A typical value might be between 1 and
4 pixels depending on style and video mode. This is a simulated
surface that appears to be rotated with respect to the Z axis.
This is a design element that could be used to delineate, set
off, or organize an area that might contain control buttons,
for example. Since it is a simulated surface
it has the property of reflections of light from the light source.
The InnerBevelWidth specifies a beveled inside edge to the
panel, button or frame. A typical value might be between 1 and
4 pixels depending on style and video mode. This is another
simulated surface that appears to be rotated with respect to the
Z axis. This is another design element that could be used to
delineate, set off, or organize an area that might contain
control buttons, for example. Since it is a simulated surface
it has the property of reflections of light from the light source.
The FaceWidth specifies whether the entire face of the panel
has a uniform color or the face of the panel is a rim or border
of a uniform color. The Face may have both an outer bevel and
an inner bevel, or just one or the other, or none. A panel may
be drawn that may contain a second panel superimposed within it
with different properties. By layering multiple, superimposed
Draw3DBox() calls, a sculptured, 3D embossed, incised, or rimmed
and beveled panel may be constructed. This is a design element
that represents a flat surface. It could be used as the
background of an area to contain or organize control buttons,
list boxes, radio controls, etc.
The simulated 3D shape displayed on the screen (since it
represents a geometric surface), must have a source illumination
direction to provide the illusion of the 3rd dimension (the
simulated Z axis). The SunShow direction of light source is the upper,
left corner, and cannot be changed. To heighten the 3-D illusion, the
bevels should reflect different light levels with respect to
their orientation to the illumination direction. Therefore,
there are two bevel color indices, depending on whether the
bevel is oriented toward or away from the light. If the beveled
surface is oriented toward the light, it will reflect more
light, thus will have a brighter color index (light grey or
bright white, for example. If the beveled surface is oriented
away from the light, it will reflect less light, thus will have
a darker color index (dark grey, for example). nLightColor
specifies the surface oriented toward the light, while
nShadowColor specifies the surface oriented away from the light.
nLightColor and nShadowColor normally are used as a raised
effect, but can be swapped for inset effect.
The simulated light source heightens the three dimensional illusion of shapes such as beveled edges, buttons, panels, frames, radio controls, etc. While Draw3DBox() may be regarded as similar to an ordinary draw box function, the real value of this function lies in its use (with SunSayXY, SunGetXY, DrawInButton, DrawOutButton, etc.) in the building up of components or modules into graphical objects containing all the elements necessary to operate a portion of your application. The graphical object could be, for example, a control panel object containing 'n' buttons with labels, proportional fonts, etc.
Draw3DBox() can also be used to draw 3d vertical separator bars by specifying X1 equal to X2. Draw3DBox() can also be used to draw 3d horizontal separator bars by specifying Y1 equal to Y2. Separator bars are design elements used in conjunction with panel surfaces, as menu or button organizational or layout aids.
The example provided below demonstrates some of the interplay between the SunShow interface functions and some of the ways that the graphical elements may be used to create an effective user interface design.
Extended Example
* The following INCLUDE is for Clipper 5.x
#INCLUDE "sunshow.ch"
* The following two lines are for FoxPro 2.5
* DO sunshow.prg
* SET LIBRARY TO SUNPRO25.PLB
* The following two lines are for FoxPro 2.0
* DO sunshow.prg
* SET LIBRARY TO SUNPRO20.PLB
status = LoadSunVideo()
status = LoadSunFonts()
nfonthandle = loadstxfont("vsys14.ptx")
IF nfonthandle < 0
? "Could not load font file vsys14.ptx"
return
ENDIF
nfontwidth = getfontwidth(nfonthandle)
nfontheight = getfontheight(nfonthandle)
nfhandle2 = loadstxfont("sona24.ptx")
IF nfhandle2 < 0
? "Could not load font file sona24.ptx"
return
ENDIF
nStatus = FindVideoMode(640, 480, 16)
IF nStatus < 0
? "Could not set mode 640 x 480 x 16"
return
ENDIF
status = draw3dbox(640, 2, 0, SUN_BWHITE, SUN_GREY, SUN_WHITE, 0, 0, 639, 479)
status = draw3dbox(0, 1, 1, SUN_BWHITE, SUN_GREY, SUN_WHITE, 20, 20, 180, 220)
status = sunsayxy(20+10, 20-4, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
"Raised Group Box")
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+20, ;
30+10+nfontwidth+4, 20+20+nfontheight)
status = sunsayxy(30+40, 20+20+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
"Item 1")
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+40, ;
30+10+nfontwidth+4, 20+40+nfontheight)
status = sunsayxy(30+40, 20+40+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
"Item 2")
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+60, ;
30+10+nfontwidth+4, 20+60+nfontheight)
status = sunsayxy(30+40, 20+60+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
"Item 3")
status = sunsayxy(30+10+3, 20+60+1, nfonthandle, SUN_BLACK, 256, "", "x")
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+80, ;
30+10+nfontwidth+4, 20+80+nfontheight)
status = sunsayxy(30+40, 20+80+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
"Item 4")
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+100, ;
30+10+nfontwidth+4, 20+100+nfontheight)
status = sunsayxy(30+40, 20+100+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
"Item 5")
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+120, ;
30+120, 20+120+nfontheight+2)
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+140, ;
30+120, 20+140+nfontheight+2)
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 30+10, 20+160, ;
30+120, 20+160+nfontheight+2)
status = draw3dbox(0, 1, 1, SUN_GREY, SUN_BWHITE, SUN_WHITE, 200, 20, 350, 220)
status = sunsayxy(200+10, 20-4, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
"Inset Group Box")
status = DrawOutButton(6, 31, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "BUTTON1")
status = DrawOutButton(9, 31, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "BUTTON2")
status = DrawOutButton(12, 31, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "BUTTON3")
status = DrawInButton(15, 31, 8, SUN_RED, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "BUTTON4")
status = DrawOutButton(18, 31, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "BUTTON5")
status = DrawOutButton(21, 31, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "BUTTON6")
* Vertical separator bar
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 370, 20, 370, 220)
status = draw3dbox(0, 1, 0, SUN_BWHITE, SUN_GREY, SUN_WHITE, 390, 20, 620, 90)
status = sunsayxy(390+10-1, 50-1, nfonthandle, SUN_BWHITE, SUN_WHITE, "", ;
"Raised panel with raised text")
status = sunsayxy(390+10, 50, nfonthandle, SUN_BLACK, 256, "", "Raised panel ;
with raised text")
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 390, 120, 620, ;
190)
status = sunsayxy(390+10+1, 150+1, nfonthandle, SUN_BWHITE, 256, "", "Inset ;
Panel with inset text")
status = sunsayxy(390+10, 150, nfonthandle, SUN_BLACK, 256, "", "Inset Panel ;
with inset text")
* Horizontal separator bar
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 390, 220, 620, ;
220)
* Horizontal separator bar
status = draw3dbox(0, 1, 0, SUN_GREY, SUN_BWHITE, SUN_WHITE, 20, 245, 620, 245)
status = draw3dbox(0, 2, 0, SUN_BWHITE, SUN_GREY, SUN_WHITE, 20, 270, 300, 400)
status = draw3dbox(3, 1, 1, SUN_BWHITE, SUN_GREY, SUN_WHITE, 20+8, 270+8, ;
300-8, 400-8)
status = sunsayxy(20+30, 300, nfonthandle, SUN_BLACK, SUN_WHITE, "", "Raised ;
panel with raised frame")
status = sunsayxy(20+30-1, 330-1, nfhandle2, SUN_BWHITE, SUN_WHITE, "", ;
"Raised text")
status = sunsayxy(20+30+1, 330+1, nfhandle2, SUN_GREY, 256, "", "Raised text")
status = sunsayxy(20+30, 330, nfhandle2, SUN_BLACK, 256, "", "Raised text")
status = draw3dbox(0, 2, 0, SUN_BWHITE, SUN_GREY, SUN_WHITE, 320, 270, 620, ;
400)
status = draw3dbox(0, 1, 1, SUN_GREY, SUN_BWHITE, SUN_WHITE, 320+8, 270+8, ;
620-8, 400-8)
status = sunsayxy(320+30, 300, nfonthandle, SUN_BLACK, SUN_WHITE, "", "Raised ;
panel with inset frame")
status = sunsayxy(320+30-1, 330-1, nfhandle2, SUN_GREY, SUN_WHITE, "", "Inset ;
text")
status = sunsayxy(320+30+1, 330+1, nfhandle2, SUN_BWHITE, 256, "", "Inset ;
text")
status = sunsayxy(320+30, 330, nfhandle2, SUN_BLACK, 256, "", "Inset text")
status = draw3dbox(0, 2, 0, SUN_BWHITE, SUN_GREY, SUN_WHITE, 20, 415, 620, 455)
status = DrawOutButton(54, 5, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button1")
status = DrawOutButton(54, 14, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button2")
status = DrawOutButton(54, 23, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button3")
status = DrawInButton(54, 32, 8, SUN_RED, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button4")
status = DrawOutButton(54, 41, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button5")
status = DrawOutButton(54, 50, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button6")
status = DrawOutButton(54, 59, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button7")
status = DrawOutButton(54, 68, 8, SUN_BLACK, SUN_WHITE, SUN_BWHITE, SUN_GREY, ;
SUN_BLACK, "Button8")
editstr1 = "Edit field 1"
status = sungetxy(30+10+2, 20+120+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
@editstr1)
editstr2 = "Edit field 2"
status = sungetxy(30+10+2, 20+140+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
@editstr2)
editstr3 = "Edit field 3"
status = sungetxy(30+10+2, 20+160+2, nfonthandle, SUN_BLACK, SUN_WHITE, "", ;
@editstr3)
status = sleep(20)
status = unloadfont(nfonthandle)
status = unloadfont(nfhandle2)
status = textmode()
set library to
return
See also
DrawInButton(), DrawOutButton(), DrawBox(), GetFontWidth(),
GetFontHeight(), GetTextWidth(), LoadxxxFont(), SunGetXY(),
SunPrintSXY(), SunSayXY(), UnLoadFont()
Return to Technical Support, Notes, Tips, Tricks
and Programming Information
Return to SunShow Professional Page