quickstart    sgxDoc    sgxDocFull

sgx.pbi

Included Files:
Included in:

Overview


Description

sgx is a screen-gadget library for PureBasic programmers to create and manage simple GUI-elements in a fullscreen or windowed screen.

it's available as sourcecode to be included in your projects. it's currently only available for Windows Operating Systems (though the code is pretty straight PB code). there are two versions: a single-file version that only contains the necessary files to just use sgx and a multi-file version in case you want to make changes to the sgx code, including the gimp files for the image files and some tools to build a single-file version from that.

with this library you can create simple GUI objects statically or dynamically of different type and appearance, modify them, display them easily, examine user actions and process events. sgx elements are accessed by ID (index-like, starting with index 1). the appearance is defined by designs, whereas you can create own designs with sets of images (there is also an instant design "lowbudget" which does not need any image files). currently there is no event queue, you will recognize events by checking for fields of your sgx elements.

currently available gadget types:
- sgxCursor
- sgxButton (including toggle buttons and buttons with a user sprite)
- sgxText
- sgxCheckbox
- sgxCombo
- sgxScrollbar
- sgxTrackbar
- sgxEdit
- sgxWin
- sgxTable
- sgxSpriteGadget
- sgxArea
- option gadgets / radio buttons are available through grouping


the documentation includes
- a quick start (sgxDoc\sgx.html)
- a full reference (sgxDoc\sgxDocFull.html)
- a smaller reference (sgxDoc\sgxDoc.html) without sgx internals (some links to sgx internals may not work in that document thought!)
- examples in the directory 'sgxDoc\'
- _README.TXT contains further informations

the references are rather technical, so use the quickstart and the examples to get the basic mechanics of sgx.


all global identifiers start with "sgx.." or "*sgx.." or "#sgx.."
globals, functions, macros, constants (#..) and pointer (*..) starting with "sgx_.." (with an underscore) as are basically used internally.
structures (sgxS_..) are also basically used internally but the documentation of sgxS_GADGET for example might be usefull nonetheless.
constants are only documented by the documentation of the functions etc. whith which they are to be used.
sgx uses implicit integer type definitions, so don't change the default type before including sgx.
if you used DisableDebugger before including sgx you should repeat it after the include statement because the debugger will be enabled.


thanks to the PureBasic team and the community / the forums.

[this document was blithely generated with jaPBdoc :) ]

Top, Back


Constants
#sgxTypeButton
#sgxTypeButtonToggle
#sgxTypeCursor
#sgxTypeCheckbox
#sgxTypeScrollbarVer
#sgxTypeScrollbarHor
#sgxTypeScrollbar
#sgxTypeTrackbarVer
#sgxTypeTrackbarHor
#sgxTypeTrackbar
#sgxTypeEdit
#sgxTypeWin
#sgxTypeSpriteGadget
#sgxTypeCombo
#sgxTypeTable
#sgxTypeText
#sgxTypeArea
#sgxAlignCheckboxTextRight
#sgxAlignCheckboxTextLeft
#sgxAlignTextLeft
#sgxAlignTextRight
#sgxAlignTextCenter
#sgxAlignTextJustifySpaces
#sgxAlignTextJustifyCharacters
#sgxStyleThin
#sgxStyleHover
#sgxStyleHoverThin
#sgxStyleGridV
#sgxStyleGridH
#sgxStyleGrid
#sgxStyleFitCellW
#sgxStyleFitCellH
#sgxStyleNoBG
#sgxStyleReverse
#sgxStyleResizable
#sgxRightclickUnsetNone
#sgxRightclickUnsetNoGroup
#sgxRightclickUnsetAll
#sgxStateNone
#sgxStateOff
#sgxStateOn
#sgxWinStateNormal
#sgxWinStateMinimizing
#sgxWinStateMinimized
#sgxWinStateRestoring
#sgxWinStateClosing
#sgxWinStatePresenting
#sgxTextcursorTypeIBeam
#sgxTextcursorTypeTeeth
#sgxTextcursorTypeLine
#sgxTextcursorTypeLine2
#sgxTextcursorTypeLine3
#sgxTextcursorTypeCaret
#sgxAnimFade
#sgxAnimSizeW
#sgxAnimSizeH
#sgxAnimSize
#sgxAnimRoll
#sgxAnimZoom
#sgxDrawNone
#sgxDrawDesign
#sgxDrawText
#sgxDrawTextNoOffset
#sgxKeyLayQwerty
#sgxKeyLayQwertz
#sgxMaxStaticGagdets
the numbers of sgx element you can create with static IDs (maximum ID). dynamic IDs start from there on. you can set this constant before including sgx, or use the default 500.

Top, Back


Structures and Interfaces
sgxS_Design
the basic structure of an sgx design.
sgxS_Mouse
type of variable sgx_m to store various mouse states
sgxS_groupElem
data stored as elements of list sgxGroups; associates sgx element IDs to group IDs via sgxSetGroup
sgxS_pendingEvents
temporary event data stored as elements of list sgx_pendingEvents to trigger the according event with the next call of sgxExamine
sgxS_Tip
allocated in sgxTip when a tooltip is added to an sgx element and is stored in field '*tip' of the structure sgxS_GADGET
sgxS_Animation
animation data temporarily used during window animations and stored as elements of map sgx_animations; is being populated in sgx_addAnimation
sgxS_ListWrapper
just a linked list wrapped in a structure to use it as optional function parameter via pointer in sgxSetState (used by sgxExamine)
sgxS_Table
will be allocated by sgx table elements and stored in field '*table' of the structure sgxS_GADGET
sgxS_GADGET
the basic structure of an sgx element.

Top, Back


Global Variables
sgx.sgxS_GADGET(0)
empty dummy array only to support autocompletion for fields of the sgx element structure sgxS_GADGET. the PB-IDE uses this for autocompletion of fields, but sgx(id) is actually a macro and not an array. no other use of this one and it could also be commented out. also remember that when using this the debugger the tooltip in the editor will say 'index out of bounds' if you mark 'sgx(id)' in the IDE because it does not evaluate the macro.
sgxCell.sgxS_GADGET(0, 0, 0)
empty dummy array only to support autocompletion for macro sgxCell(). see documentation of the dummy array sgx().
sgxGroups.sgxS_groupElem()
list of radio group elements
sgxDesign.sgxS_Design()
list of loaded designs
sgxActiveWin = -1
the currently active (foreground) window id or -1 if no window is active.
sgxStdFont = LoadFont(#PB_Any, "Arial", 8)
font used for caption of minimized windows and as a default for the current font.
sgxTopID = -1
ID of the element currently under the mouse or -1 if no element is there.
sgxTipDelay = 500
delay for tip popup in milliseconds
sgxHoldDelay = 400
delay for first hold event in milliseconds
sgxHoldInterval = 30
interval of hold events in milliseconds
sgxRightclickUnset = #sgxRightclickUnsetAll
per default (#sgxRightclickUnsetAll) rightclick on checkboxes and togglebuttons changes their state to unchecked / not pushed. if set to #sgxRightclickUnsetNoGroup then this will only be applied to elements that are not part of a radiogroup. #sgxRightclickUnsetNone completely disables this behaviour.
sgxAnimTime = 400
duration of window animations in milliseconds. you can set this to 0 to effectively disable animations.
sgxWinCloseEnabled = 1
(bool) adjusts if windows can be closed by rightclick
sgxNumberOfElements = 0
number of currently existing and valid sgx elements

Top, Back


Functions and Macros
sgx(index)
use this macro to access the structure of your sgx elements.
sgxNew(id)
create a new sgx object.
sgxInBounds(index)
returns #True if 'index' is within bounds of the basic sgx element array, otherwise it returns #False.
sgxSetCurrentParent(id)
set the parent for coming creations of new sgx elements.
sgxSetParent(id, parent)
sets or changes the parent of an sgx element.
sgxEach(it)
use this macro to iterate through the elements.
sgxMoveOnTop(id)
make an sgx window (#sgxTypeWin) active and foreground or move an element above its siblings.
sgxGetElementAt(x, y)
returns the ID of the topmost sgx element at the given position on screen, or -1 if no sgx element is found there.
sgxGetTopLevel(id)
returns the ID of the topmost parent.
sgxMove(id, x, y, relative = #True)
change the position of an sgx element.
sgxSetDisabled(id, disabled = #True)
disable or enable an sgx element.
sgxResize(id, w, h)
change the size of an sgx element.
sgxCloseLevel(closeAllLevels = #False)
call this function when you finished the creation of a window or table and it's childs.
sgxDebugElem.s(id, multiline = #False)
returns a string with information about the element's attributes.
sgxDebugTree.s(id = -1)
returns a string with information about the elements attributes and their hierarchy.
sgxSetFont(font)
set the font for coming creations of new sgx elements.
sgxSetGroup(id, groupID)
add an sgx element to a radio group.
sgxGetGroup(id)
returns the groupID of an sgx element, or -1 if the element does not belong to a radio group.
sgxSetDimensions(width, height)
tell sgx about the screen dimensions you use.
sgxFree(id)
free / delete an sgx element, including childs.
sgxFreeChildsOf(parent)
free / delete all childs of an sgx element, including their own childs.
sgxSetShow(id, show, recursively = #True, ignoreWindows = #True)
shows or hides an element.
sgxMinimizeWin(id)
initializes minimizing of window.
sgxRestoreWin(id)
initializes restoring of window.
sgxCloseWin(id)
initializes closing of a window and it's child windows.
sgxPresentWin(id)
initializes presenting of a window and it's child windows.
sgxSetWinAnimStyle(winState, winAnimStyle)
configures window animations.
sgxSetTextcursorType(textcursorType)
changes the type of the textcursor used by sgxEdit elements.
sgxSetText(id, text.s)
changes the text of an sgx element and refreshes it.
sgxSetResizable(id, resizable = #True)
make an element resizeable via the mouse.
sgxSetMinSize(id, minWidth, minHeight)
set the minimum size allowed for manually resizing elements via mouse.
sgxSetScrollMax(id, max)
change the range of a scrollbar/trackbar.
sgxSetState(id, state, handleRadioGroups = #True, *changed.sgxS_ListWrapper = 0)
changes the state of an sgx element and refreshes it if necessary.
sgxSetEmsContainer(*emsContainer.Integer)
tell sgx about your 'ems' variable.
sgxSetDesign(*design.sgxS_Design, id = -1)
set the design for coming creations of new sgx elements, or change the design of an sgx element.
sgxSetAlpha(alpha, id = -1, recursive = #False)
set the alpha value for coming creations of new sgx elements (default alpha is 255, no transparency), or change the alpha value of an sgx element.
sgxCell(table, i, k)
use this macro to access the structure of your sgx elements if they are cells of a table and you want to access them via their position in the table.
sgxCellId(table, i, k)
returns the ID of a table-cell, or 0 for empty cells or if it fails, which happens if table is not a valid sgx table element or if the coordinates are out of the table's dimensions.
sgxCellAssign(i, k, id, table = -1)
assigns an sgx element to a cell of a table or removes it.
sgxSetKeyboardLayout(layout = #sgxKeyLayQwerty, keystrokeDelay_1 = 280, keystrokeDelay_2 = 40)
configure keyboard layout and keystroke delay used by sgxEdit elements (via sgx_keyboardEdit).
sgxLoadDesign(design.s = "lowbudget", basecolor = -1)
loads a design.
sgxRefreshDesign(*design.sgxS_Design)
refresh the design.
sgxCursor(id)
creates an sgx cursor element and returns it's ID.
sgxButton(id, x, y, w, h, text.s, toggle = #sgxStateNone, sprNr = -1, x2 = 5, y2 = 5)
creates an sgx button element and returns it's ID.
sgxCheckbox(id, x, y, w, h, checked = #sgxStateOff, text.s = "", align = #sgxAlignCheckboxTextRight)
creates an sgx checkbox element and returns it's ID.
sgxScrollbar(id, x, y, w, h, w2, h2, max, state = 0, style = 0)
creates an sgx scrollbar element and returns it's ID.
sgxTrackbar(id, x, y, w, h, w2, h2, max, state = 0, style = #sgxStyleGrid)
creates an sgx trackbar element and returns it's ID.
sgxEdit(id, x, y, w, h, text.s = "", maxLines = -1)
creates an sgx edit element and returns it's ID.
sgxWin(id, x, y, w, h, text.s = "", style = 0)
creates an sgx window element and returns it's ID.
sgxSpriteGadget(id, x, y, sprNr)
creates an sgx sprite container and returns it's ID.
sgxArea(id, x, y, w, h)
creates an sgx area container and returns it's ID.
sgxTip(id, text.s)
creates a tooltip for an sgx element.
sgxCombo(id, x, y, w, h, text.s = "")
creates an sgx combo element and returns it's ID.
sgxText(id, x, y, w = -1, h = -1, text.s = "", style = 0, margin = 3, textalign = #sgxAlignTextLeft, wordwrap = #False)
creates an sgx text element and returns it's ID.
sgxTable(id, x, y, columns, lines, margin, style = #sgxStyleGrid)
creates an sgx table element and returns it's ID.
sgxRefreshAll()
refresh all existing sgx elements, if you modified the design for instance.
sgxRefresh(id, mode = #sgx_refreshNormalWithTip)
refresh an sgx element.
sgxExamine(mousex = -1, mousey = -1)
process actions / events and update the field data of all sgx element.
sgxDisplay()
display all sgx element on screen.
sgxDisplayCursor()
display the sgx mouse cursor on screen.
sgxDisplayID(id)
display an sgx element on screen.

Top, Back


sgxS_Design

the basic structure of an sgx design.
stored in field '*design' of the structure sgxS_GADGET.
returned by sgxLoadDesign if the loading succeeds.
type of list sgxDesign().
type of variable *sgx_CurrentDesign and can be passed to sgxSetDesign.

the fields onBeginDraw and onEndDraw are of the following type:
 Prototype sgx_onBeginDraw(id, sprType, w, h, disabled=#False) 
Prototype sgx_onEndDraw (id, sprType, w, h, disabled=#False)
you can assign function pointers directly to these fields if you have defined a function that should be called during the drawing proccess of an sgx element. they will be called inside a StartDrawing/StopDrawing block and the current drawing output will already have been cleared with transparent black when onBeginDraw() is called. the parameters passed to the callbacks include the ID of the sgx element and the type of the sprite (#sgx_GadgetSpr..) that is currently being redrawn as well as the width and height of the current drawing output and if the sprite should visualize a disabled state, in which case the sprite will not have been cleared but instead contains the appearance of the enabled state of that sprite type which can be modified to make it look disabled (or cleared and redrawn if you wish).
make sure you use a drawing mode with alpha channel and use colors that include alpha information, otherwise your drawing will stay invisible.

onBeginDraw() can be used to replace steps in the redraw process.
with the return value you can define what sgx should draw after the call of your callback:
onEndDraw() can be used to just add or overdraw something after sgx has finished it's drawing operations. it works just like onBeginDraw() except you don't have to return anything.

the sprite types #sgx_GadgetSprChecked and #sgx_GadgetSprTextCursor have the same value as #sgx_GadgetSprPushed, so checking for these two would make it necessary to check the element type also (checkbox or edit).
all element types might also be called with a sprite type of #sgx_GadgetSprTip, to redraw the tooltip of the element.
other sprite types can differ depending on the element type

here is an example in form of an onBeginDraw() custom callback that shows how you could handle the different cases.
it could be also much simpler though, for example by handling only the tooltip case and return the default in all other cases
 Procedure myOnBeginDraw(id, sprType, w, h, disabled=#False) 
Static retval

; our default returnvalue (sgx should draw everthing as usual after this function has finished)
retval = #sgxDrawDesign | #sgxDrawText

If sprType = #sgx_GadgetSprTip
; the element's tooltip sprite is currently redrawn.
; you might want to handle this as a generel case, independent from element type.

ElseIf sprType = #sgx_GadgetSprResize
; the element's resize gadget is currently being redrawn.
; you might want to handle this as a generel case, independent from element type.
Else

; the other sprite types are element type dependent

If disabled
; the drawing output already contains the visuals for that sprite type and should be
; modified (or redrawn completely) to visualize a disabled state. you could also return
; the default returnvalue and do the modification in an onEndDraw callback.
EndIf

Select sgx(id)\type

Case #sgxTypeCursor
; sprType:
; #sgx_GadgetSprNormal

Case #sgxTypeButton, #sgxTypeButtonToggle
; sprType:
; #sgx_GadgetSprNormal
; #sgx_GadgetSprHover
; #sgx_GadgetSprPushed
; #sgx_GadgetSprHoverPushed
Case #sgxTypeCheckbox
; sprType:
; #sgx_GadgetSprNormal
; #sgx_GadgetSprHover
; #sgx_GadgetSprChecked
Case #sgxTypeScrollbarVer, #sgxTypeScrollbarHor, #sgxTypeTrackbarVer, #sgxTypeTrackbarHor
; sprType:
; #sgx_GadgetSprNormal ; - bar
; #sgx_GadgetSprHover ; /
; #sgx_GadgetSprNormal2 ; - knob
; #sgx_GadgetSprHover2 ; /
Case #sgxTypeEdit
; sprType:
; #sgx_GadgetSprNormal
; #sgx_GadgetSprHover
; #sgx_GadgetSprTextCursor
Case #sgxTypeWin
; sprType:
; #sgx_GadgetSprNormal
; #sgx_GadgetSprHover
; #sgx_GadgetSprPushed ; displayed if the window is foreground or catched focus (i.e. when moving the window manually)
; #sgx_GadgetSprNormal2 ; - close gadget
; #sgx_GadgetSprHover2 ; /
Case #sgxTypeTable
; sprType:
; #sgx_GadgetSprNormal
; #sgx_GadgetSprHover
Case #sgxTypeCombo
; sprType:
; #sgx_GadgetSprNormal
; #sgx_GadgetSprHover
; #sgx_GadgetSprPushed ; the opened combo
; #sgx_GadgetSprHover2 ; open combo hover effect
Case #sgxTypeText
; sprType:
; #sgx_GadgetSprNormal
; #sgx_GadgetSprHover
EndSelect
EndIf

; if you have actually drawn something in one of the branches above then your returnvalue
; should not include the flag #sgxDrawDesign, otherwise sgx will paint over your content.
ProcedureReturn retval
EndProcedure

Elements:

name.s
name or path of the design like "lowbudget" or "..\sgxDesigns\blue" for example
basecolor.i
basecolor of the design as specified at sgxLoadDesign or as defined in the design's 'parts' image file
c.i[20]
the design pallete (populated in sgx_MakePalette)
img.sgx_S_Image[30]
array of the design images of type sgx_S_Image that will be drawn on the sgx element sprites during a refresh like the parts of the border or the background for example; accessed with #sgx_Design.. constants as indices
onBeginDraw.sgx_onBeginDraw
optional custom draw callback called at the beginning of element redraw (see structure description)
onEndDraw.sgx_onEndDraW
optional custom draw callback called at the end of element redraw (see structure description)

Top, Back


sgxS_Mouse

type of variable sgx_m to store various mouse states

Elements:

x.i
x-position of mouse on screen
y.i
y-position of mouse on screen
dx.i
delta x of the mouse position
dy.i
delta y of the mouse position
dlimit.i
the x/y delta of the mouse position that must occure to make an currently shown sgx tooltip disappear again
leftclick.i
1 if the left mouse button has been pushed and was not pushed previously, otherwise 0
leftdown.i
1 if the left mouse button is currently pushed, otherwise 0
leftup.i
1 if the left mouse button has been released, otherwise 0
rightclick.i
1 if the right mouse button has been pushed and was not pushed previously, otherwise 0
rightdown.i
1 if the right mouse button is currently pushed, otherwise 0
rightup.i
1 if the right mouse button has been released, otherwise 0
leftdown_prev.i
1 if the left mouse button was pushed previously, otherwise 0
rightdown_prev.i
1 if the right mouse button was pushed previously, otherwise 0
wheel.i
the amount of steps the mousewheel has ben rotated
wheelSign.i
1 if 'wheel' is positive or 0 (scrolling 'up' or not scrolling), -1 if 'wheel' is negative (scrolling 'down')
cursor.i
ID of the current sgx cursor element used as the mouse cursor or -1 if no mouse cursor is set (if none has been created or if it has been freed). will be set by sgxCursor.

Top, Back


sgxS_groupElem

data stored as elements of list sgxGroups; associates sgx element IDs to group IDs via sgxSetGroup

Elements:

id.i
groupID.i

Top, Back


sgxS_pendingEvents

temporary event data stored as elements of list sgx_pendingEvents to trigger the according event with the next call of sgxExamine

Elements:

id.i
ID of the sgx element whose event field should be set
changed.i
the value that should be set for the 'changed' field
resized.i
the value that should be set for the 'resized' field (0 or 1)
refreshed.i
the value that should be set for the 'refreshed' field

Top, Back


sgxS_Tip

allocated in sgxTip when a tooltip is added to an sgx element and is stored in field '*tip' of the structure sgxS_GADGET

Elements:

spr.i
the PB sprite that is displayed as the tooltip
w.i
width of the tooltip
h.i
height of the tooltip
text.s
the text of the tooltip
timer.i
a timer for the popup delay
show.i
0=sleeping ; 1=show ; -1=hide (which means do not popup again before element mouseout. will be reset to 0 on 'no hover')

Top, Back


sgxS_Animation

animation data temporarily used during window animations and stored as elements of map sgx_animations; is being populated in sgx_addAnimation

Elements:

startTime.i
startX.i
startY.i
startW.i
startH.i
startAlpha.i
endX.i
endY.i
endW.i
endH.i
endAlpha.i

Top, Back


sgxS_ListWrapper

just a linked list wrapped in a structure to use it as optional function parameter via pointer in sgxSetState (used by sgxExamine)

Elements:

Listlist_.i()

Top, Back


sgxS_Table

will be allocated by sgx table elements and stored in field '*table' of the structure sgxS_GADGET

Elements:

w.i
number of columns
h.i
number of lines
*cells
memory block to store cell ids
*gridx
memory block to store x-positions of vertical grid lines
*gridy
memory block to store y-positions of horizontal grid lines

Top, Back


sgxS_GADGET

the basic structure of an sgx element.

some fields are used differently depending on the element type:

x2, y2, w2 and h2 are set to x, y, w and h as a default during element creation in sgx_PassStandardValues() and are used as follows:
- sgxButton x2,y2: offset for optional button sprite.
- sgxScrollbar/Trackbar x2,y2,w2,h2: position and size of knob.
- sgxCombo h2: height of open hover frame (same as h actually). while combo is open, h is temporarily stored in h2 and becomes the expanded height itself.
- sgxEdit x2,y2,w2,h2: 'client area' or text clipping area (area inside the element where text appears).
- sgxCheckbox x2,y2,w2,h2: overall size and knob-relative position (see the notes on sgxCheckbox).
- sgxWin: x2,y2,w2,h2: hold the original position and size while minimized.

width:
- the height of the knob of a vertical scrollbar/trackbar and the width of the knob of a horizontal scrollbar/trackbar. used for scrollpos calculation and knob positioning.
- sxgWin: the height of the titlebar. often checked as a bool value to know if a titlebar exists (but its usually not 1, so don't compare it to #True).

max:
- sgxScrollbar/sgxTrackbar: the maximum value (minimum is 0)
- sgxEdit: the maximum number of lines allowed
- sgxCombo: 0 if the combo is closed. 1 if it's opened ('maximized')

state (see also sgxSetState):
- sgxSpriteGadget: the PB Sprite number or 0.
- sgxCombo: the currently selected entry number in the range of 1 to the number of entries (both inclusive). default is 1.
- sgxWin: one of the #sgxWinState.. values
- toggle buttons: 1 if the button is toggled/pushed, otherwise 0.
- sgxCheckbox: 1 if the checkbox is checked, otherwise 0.
- sgxScrollbar/sgxTrackbar: the current value in the range of 0..max (both inclusive)
never compare the state field to the #sgxState.. values because these are used only during element creation.

Elements:

xToParent.i
x-position relative to parent position
yToParent.i
y-position relative to parent position
x.i
x-position on screen (absolute)
y.i
y-position on screen (absolute)
w.i
width of the element
h.i
height of the element
type.i
type of the element (#sgxType...)
parent.i
parent element ID or -1 for top-level elements
hasChilds.i
(bool) true if the element has childs
x2.i
type dependent. see structure description.
y2.i
type dependent. see structure description.
w2.i
type dependent. see structure description.
h2.i
type dependent. see structure description.
auto.i
auto adaptation flags (combination of #sgx_Auto.. constants)
*treeElem.sgx_llS_elem
element in the tree list. treeElem\node (list of childs) will 0 if the element does not have childs.
*design.sgxS_Design
the design used by the sgx element
text.s
window title / button caption / text of sgxText or sgxEdit / checkbox label / etc. if you need the text unmodifed by automatic word wrap see 'origText'.
width.i
type dependent. see structure description.
textw.i
width of the element's text. for sgxText elements this is the text width of the longest line in case of multiline text.
texth.i
height of the element's text. line height in case of multiline text.
textpos.i
used by sgxEdit elements as current cursor position in characters including linebreaks where 0 means at the beginning of text / before the first character.
textcursor.sgx_S_Point
position (in pixel) of textcursor of sgxEdit elements inside the text clipping area (as defined by x2,y2,w2 and h2)
textalign.i
like #sgxAlign.. for sgxCheckbox and sgxText elements. also used by sgxEdit elements for horizontal text scrolling.
textfontID.i
the PB font ID used for drawing text during element refresh. set to sgx_CurrentFontID on element creation.
origText.s
original text i.e. as specified at creation as opposed to field 'text' which might be modified due to automatic word wrap etc.
origW.i
original width as specified at creation as opposed to field 'w' (real resulting width). used for example to store the -1 that might have been used for automatic sizing.
origH.i
original height as specified at creation as opposed to field 'h' (real resulting height). used for example to store the -1 that might have been used for automatic sizing.
*tip.sgxS_Tip
tooltip data (will be allocated only if needed).
*table.sgxS_Table
will be allocated for tables only (#sgxTypeTable)
scrollpos.i
used for knob positioning by scrollbars/trackbars and for vertical text scrolling by sgxEdit elements.
spr.i[8]
the sprites used for displaying
alpha.i
transparency. can be set via sgxSetAlpha
alpha2.i
original transparency stored during animations
sys0.sgx_S_Box
some box coordinates relative to the elements origin/position defining the close button area of windows to detect mouse events there.
hover.i
1 if the mouse is hovering the element. 0 if it doesn't. an element might not get the hover event if some element (an sgxEdit element or an sgxScrollbar for example) has catched the focus.
state.i
type dependent. see structure description.
max.i
type dependent. see structure description.
changed.i
fired once if the elements state changed. for scrollbars and trackbars: the value by that the state changed. fired also for sgxEdit element if the text or the cursor position has changed.
resizable.i
1 if the element can be resized with the mouse. otherwise 0. can be set via sgxSetResizeable.
minWidth.i
the smallest width allowed for manually resizing elements via mouse. can be set via sgxSetMinSize.
minHeight.i
the smallest height allowed for manually resizing elements via mouse. can be set via sgxSetMinSize.
resized.i
fired once if the elements size has been changed by sgxResize.
refreshed.i
fired once if the element has been refreshed. this may include partial refresh like updating only the tooltip of an element and does not necessarily mean that the element has been redrawn but on the other hand any redraw will tigger this event.
show.i
if #True then the element will be displayed and receives events, otherwise #False to hide the element. should be changed via sgxSetShow.
show2.i
original visibility stored during animations
style.i
type dependent. see documentation of the compose functions that support it like sgxText or sgxCheckbox.
passive.i
0 by default. if set to 1 the element won't catch events or move in front. usefull for background sprite gadgets.
disabled.i
0 by default. if set to 1 the element won't catch events or move in front and will be displayed dimmed. can be set via sgxSetDisabled
margin.i
space in pixels between the elements boundary and it's content. used by sgxText and sgxTable elements. also used by sprite buttons to store the sprite offset for displaying when pushed.
leftclick.i
(bool) fired once with first left mouse button down

Top, Back


sgx(index)

use this macro to access the structure of your sgx elements.

if you try to access invalid sgx objects you might get one of the following errors:
(use Menu > Debugger > Callstack to find out where the error might have been caused)
 ; this will cause an error: 
;Debug sgx(-123)\text ; "[ERROR] sgx array index out of bounds: sgx(-123)"

; this will cause an error if we did not create an element with this ID:
;Debug sgx(345)\text ; "[ERROR] Pointer is null."

; this will NOT cause an error since the index is ok and we check if that element exists:
If sgx(345)
; but we might not get here
Debug sgx(345)\text
EndIf
 

Parameters:

index
ID of a valid and existing sgx element (if structure fields will be accessed), where index can be in the range of 1 .. sgx_CURRENT_MAX_DYNAMIC_GADGETS. you can check if the ID is valid by a nonzero value of 'sgx(index)' (without structure field access).

Top, Back


sgxNew(id)

create a new sgx object.
returns the ID of that newly created object, or 0 if creation failed.
you should use the compose functions like sgxButton etc. to create actual sgx elements.

Parameters:

id
the ID to be used for the new object, where id can be in the range of 1 .. sgx_LIMIT_STATIC_GADGETS, or -1 to dynamically generate an ID.
if the ID is already in use, the according element is freed (including childs) and replaced.

Top, Back


sgxInBounds(index)

returns #True if 'index' is within bounds of the basic sgx element array, otherwise it returns #False.
a return value of '#True' does not say anything about the existence or validity of a possible element at that position.

Parameters:

index
the index that is to be checked.

Top, Back


sgxSetCurrentParent(id)

set the parent for coming creations of new sgx elements.
needed if you want to add childs later. calls of this function in combination with sgxCloseLevel should not be nested.

Parameters:

id
ID of the element to become the current parent

Top, Back


sgxSetParent(id, parent)

sets or changes the parent of an sgx element.
used at element creation and also in sgxCellAssign.
the child is not automatically repositioned, use sgxMove if necessary.

Parameters:

id
ID of the child element which parent is to be changed.
parent
ID of the element to become the new parent

Top, Back


sgxEach(it)

use this macro to iterate through the elements. the order in which the elements are iterated is undefined.
usage example:
 ;Define id  ; needed if EnableExplicit is used 

For sgxEach(id)
Debug sgx(id)\text
Next

Parameters:

it
choose your iterator variable here that will contain the ID of the sgx elements. this variable is used in the for/next loop as is and must have been declared previously if EnableExplicit is used.

Top, Back


sgxMoveOnTop(id)

make an sgx window (#sgxTypeWin) active and foreground or move an element above its siblings. if the element is not a window then the parent window will be activated additionally.

Parameters:

id
the ID of the sgx element

Top, Back


sgxGetElementAt(x, y)

returns the ID of the topmost sgx element at the given position on screen, or -1 if no sgx element is found there. passive elements are ignored.

Parameters:

x
x-position on screen in pixels
y
y-position on screen in pixels

Top, Back


sgxGetTopLevel(id)

returns the ID of the topmost parent.

Parameters:

id
ID of child element. if this element does not have parents, it is the top level itself and thus returned.

Top, Back


sgxMove(id, x, y, relative = #True)

change the position of an sgx element.
the positioning is either in absolute screen coordinates or in absolute toParent coordinates.
if you want to position the element relative to its own current position (by offset) you would calculate the offset as follows (both methods would have the same effect):
 ; moves the element 10 pixels to the right as well as down by specifiying toParent coordinates. 
sgxMove(id, sgx(id)\xToParent+10, sgx(id)\yToParent+10);

; moves the element 10 pixels to the right as well as down, using absolute screen coordinates. it's toParent-position will be updated accordingly.
sgxMove(id, sgx(id)\x+10, sgx(id)\y+10, #False);

Parameters:

id
ID of the sgx element to be moved
x
new x-position relative to parent element
y
new y-position relative to parent element
relative
by default (#True) the element will be positioned relative to it's parent. specify #False if x/y are absolute screen coordinates.

Top, Back


sgxSetDisabled(id, disabled = #True)

disable or enable an sgx element.
if the disabled/enabled state changes then the element will be refreshed.

Parameters:

id
ID of the sgx element to be disabled or enabled
disabled
#True (default) to disable the element or #False to enable it.

Top, Back


sgxResize(id, w, h)

change the size of an sgx element.
sgxTable elements determine their size by their childs and cannot be resized directly. sgxCheckbox elements resize only their knob (w,h) but their overall size (w2,h2) might be influenced by this too.

Parameters:

id
ID of the sgx element to be resized
w
the new width. one of these values:
- a positive value > 0 for an explicit width.
- a value of -2 to ignore that parameter and not change the width or to use the automatic size adjustment as specified at creation for elements which support it.
- a value of -1 to explicitly use automatic size adjustment for elements which support it.
h
the new height. one of these values:
- a positive value > 0 for an explicit height.
- a value of -2 to ignore that parameter and not change the height or to use the automatic size adjustment as specified at creation for elements which support it.
- a value of -1 to explicitly use automatic size adjustment for elements which support it.

Top, Back


sgxCloseLevel(closeAllLevels = #False)

call this function when you finished the creation of a window or table and it's childs.
note that this function will always set the current parent to its own parent and NOT necessarily to the value it had before a call of sgxSetCurrentParent.

Parameters:

closeAllLevels
if set to #True, there will be no current parent after the call and new creations will be global.
if set to #False (default), the above parent level will be the new current parent.

Top, Back


sgxDebugElem.s(id, multiline = #False)

returns a string with information about the element's attributes.

Parameters:

id
ID of the sgx element.
multiline
#False (default) to return a single line. #True to format with newlines (#LF$ / Chr(10)).

Top, Back


sgxDebugTree.s(id = -1)

returns a string with information about the elements attributes and their hierarchy.

Parameters:

id
-1 (default) to debug the whole element hierarchy. specify an element ID to only debug that element and its childs recursively.

Top, Back


sgxSetFont(font)

set the font for coming creations of new sgx elements.

Parameters:

font
a valid PB #Font. if you pass sgxStdFont or an invalid font then the current font will be reset to the default.

Top, Back


sgxSetGroup(id, groupID)

add an sgx element to a radio group.
checkboxes and/or toggle buttons can be grouped using this function so that if one element gets checked/pushed, all others will be unchecked/untoggled.
those elements can still be unchecked via righclick per default setting of variable sgxRightclickUnset, so that no element in that group would be checked/pushed.
see also sgxGetGroup.

Parameters:

id
ID of the sgx element to be added
groupID
any number. use same numbers for elements you want to group

Top, Back


sgxGetGroup(id)

returns the groupID of an sgx element, or -1 if the element does not belong to a radio group.
see also sgxSetGroup.

Parameters:

id
ID of the sgx element to be inquired

Top, Back


sgxSetDimensions(width, height)

tell sgx about the screen dimensions you use.
this isn't necessary if a screen has been opened before the first call of sgxLoadDesign.

Parameters:

width
screenwidth
height
screenheight

Top, Back


sgxFree(id)

free / delete an sgx element, including childs. the ID of the element and all its child element IDs will become invalid.

Parameters:

id
ID of the sgx element to be freed

Top, Back


sgxFreeChildsOf(parent)

free / delete all childs of an sgx element, including their own childs.

Parameters:

parent
ID of the sgx element whose childs are to be freed. this parent will remain valid, the IDs of all child elements will become invald.

Top, Back


sgxSetShow(id, show, recursively = #True, ignoreWindows = #True)

shows or hides an element.
if you hide a window including its childs and later show it again then previously hidden childs will be all visible and not restored to their actual previous visibility.

Parameters:

id
ID of the sgx element.
show
#True to show the element, or #False to hide it.
recursively
#True (default) to show/hide child elements too recursively. #False to only show/hide the element itself.
ignoreWindows
if parameter 'recursively' is #True then recursion will not traverse into child windows per default (#True). set it to #False for complete recursion including child windows.

Top, Back


sgxMinimizeWin(id)

initializes minimizing of window.
the animation might finish immediately.

Parameters:

id

Top, Back


sgxRestoreWin(id)

initializes restoring of window.
the window's 'resized' event will be triggered when the animation has finished which can be received after the next call of sgxExamine.
the animation might finish immediately.

Parameters:

id

Top, Back


sgxCloseWin(id)

initializes closing of a window and it's child windows.
the animation might finish immediately in wich case the element and its childs will have been deleted and their IDs become invalid. in that case the returnvalue is 1, otherwise 0.

Parameters:

id

Top, Back


sgxPresentWin(id)

initializes presenting of a window and it's child windows.
the window's 'resized' event will be triggered when the animation has finished which can be received after the next call of sgxExamine.
the animation might finish immediately.

Parameters:

id

Top, Back


sgxSetWinAnimStyle(winState, winAnimStyle)

configures window animations.
animation of size will make a window hide its childs during the animation. animations 'zoom' and 'roll' only work for minimizing and restoring of windows.

Parameters:

winState
the type of animation you want to configure: #sgxWinStateMinimizing, #sgxWinStateRestoring, #sgxWinStateClosing or #sgxWinStatePresenting
winAnimStyle
combination of animation styles (you can combine them with '|' (bitwise OR)):
#sgxAnimFade : animate the elements alpha value (transparency)
#sgxAnimSizeW : collapse / expand the width
#sgxAnimSizeH : collapse / expand the height
#sgxAnimSize : collapse / expand width and height
#sgxAnimZoom : zoom windows into / out of the taskbar
#sgxAnimRoll : roll windows down to / up from the taskbar

Top, Back


sgxSetTextcursorType(textcursorType)

changes the type of the textcursor used by sgxEdit elements. call this function before creating sgxEdit elements, otherwise the change takes effect with next element refresh.

Parameters:

textcursorType
one of these values:
#sgxTextcursorTypeIBeam (I-Beam type cursor)
#sgxTextcursorTypeTeeth (something like an open I-Beam cursor)
#sgxTextcursorTypeLine (vertical line)
#sgxTextcursorTypeLine2 (thicker vertical line/bar)
#sgxTextcursorTypeLine3 (vertical line/bar with some alpha blending)
#sgxTextcursorTypeCaret (caret type cursor)

Top, Back


sgxSetText(id, text.s)

changes the text of an sgx element and refreshes it.
this function may trigger the 'changed' event for sgxEdit elements which can be received after the next call of sgxExamine.

Parameters:

id
ID of the sgx element whose text is to be changed.
text
new text.

Top, Back


sgxSetResizable(id, resizable = #True)

make an element resizeable via the mouse.
sgxTable elements determine their size by their childs and cannot be resized directly.
sgxCheckbox elements resize only their knob (w,h) but their overall size (w2,h2) might be influenced by this too.
scrollbars/trackbars will resize only their bar and not their knob.
use sgxSetMinSize to ensure a minimum size.
the element's 'resized' field will be triggered every time the size changes.

Parameters:

id
ID of the sgx element.
resizable
#True (default) to make the element resizable. #False to disable resizing via mouse.

Top, Back


sgxSetMinSize(id, minWidth, minHeight)

set the minimum size allowed for manually resizing elements via mouse.
the default minimum size (if you don't call this function) is the size of the resize gadget.

Parameters:

id
ID of the sgx element.
minWidth
the smallest width allowed for resizing. must be greater 0.
minHeight
the smallest height allowed for resizing. must be greater 0.

Top, Back


sgxSetScrollMax(id, max)

change the range of a scrollbar/trackbar.
this will update the element's state if the new maximum is lower than its current state and updates the knob position. the element's 'changed' event might be triggered if the state changes.

Parameters:

id
ID of the sgx scrollbar/trackbar element.
max
new maximum possible scroll state (minimum is 0). this must be greater than 0 and will be corrected to 1 automatically if necessary.

Top, Back


sgxSetState(id, state, handleRadioGroups = #True, *changed.sgxS_ListWrapper = 0)

changes the state of an sgx element and refreshes it if necessary.
this function may trigger the 'changed' event for the element (or for other elements in a radiogroup) which can be received after the next call of sgxExamine.

Parameters:

id
ID of the sgx element whose state is to be changed.
state
the new state (don't ever use #sgxState.. values here because these are used only during element creation.).
for scrollbars and trackbars the state will not be changed if it's lower than 0 or greater than the maximum.
for toggle buttons and checkboxes specify a state of 1 for toggled/checked or 0 for not toggled/checked.
for combos the state must be in the range of 1 to the number of entries (both inclusive) otherwise the state will not be changed.
for sprite gadgets the parameter 'state' must be a valid PB sprite number or 0 to detach the current sprite. this will also update the element's size according to the size of the sprite. if you specify 0 as the sprite then the element size will be zero and you won't receive any mouse events!
to change the state of a window use sgxPresentWin, sgxMinimizeWin, sgxRestoreWin and sgxCloseWin.

handleRadioGroups
#True (default) to also handle other element's state in a possibly assigned radiogroup accordingly.
*changed
used internally by sgxExamine to correctly set the 'changed' flag for the other radiogroup members.

Top, Back


sgxSetEmsContainer(*emsContainer.Integer)

tell sgx about your 'ems' variable. since it's likely that you've got already a variable holding some 'ElapsedMilliseconds()'-like value,
you can let sgx access that data. usefull if you have better timing resolution. otherwise if you don't call this procedure then sgx will inquire PB's ElapsedMilliseconds() by itself (default).
you need to call that procedure once only.

Parameters:

*emsContainer
a pointer to your long-variable (use @).

Top, Back


sgxSetDesign(*design.sgxS_Design, id = -1)

set the design for coming creations of new sgx elements, or change the design of an sgx element.

Parameters:

*design
pointer to a loaded design (return value of sgxLoadDesign or one of the sgxDesign() list elements).
id
per default (-1), the from now on used design is set to *design. if an ID is passed, only the design of the sgx element is changed wich takes effect with the next element refresh which is not done automatically.

Top, Back


sgxSetAlpha(alpha, id = -1, recursive = #False)

set the alpha value for coming creations of new sgx elements (default alpha is 255, no transparency), or change the alpha value of an sgx element.

Parameters:

alpha
alpha value in the range of 0 (invisible) to 255 (fully opaque / no tranparency)
id
if ignored (default/-1), the from now on used default value is set to alpha. if an ID is passed, only the alpha value of the sgx element is changed. no refresh of that element is necessary, since the value is only used for display.
recursive
#False per default. if set to #True, the alpha value of the childs of the element will also be changed unless they are windows.

Top, Back


sgxCell(table, i, k)

use this macro to access the structure of your sgx elements if they are cells of a table and you want to access them via their position in the table. you can also access them the normal way via sgx though.

Parameters:

table
ID of an sgx table element (#sgxTypeTable)
i
column (starting with 0)
k
line (starting with 0)

Top, Back


sgxCellId(table, i, k)

returns the ID of a table-cell, or 0 for empty cells or if it fails, which happens if table is not a valid sgx table element or if the coordinates are out of the table's dimensions.

Parameters:

table
ID of an sgx table element (#sgxTypeTable)
i
column (starting with 0)
k
line (starting with 0)

Top, Back


sgxCellAssign(i, k, id, table = -1)

assigns an sgx element to a cell of a table or removes it. that table must either be the current parent or must be specified by parameter. the element will be removed from its current parent's child list and becomes a child of the table. it returns the same ID as passed, or 0 if assignment failed. it fails if the table is not a valid sgx table element, or if i/k are out of the bounds of the table's columns/lines.
it's recommended to create and assign the table's child elements between the table creation with sgxTable and it's associated call of sgxCloseLevel. since table cells and their assigned elements can influence each other's dimensions, they are all refreshed once with the call of sgxCloseLevel. but it's generally possible to create the childs before or after and only assign them during the creation of the table or later, though there might happen redundant double refreshing of elements.
if an id of 0 is specified, the cell will be cleared and becomes empty. in any case a possibly already assigned element at that position will be removed and freed.

sgxCellAssign should be used in one of the following ways:

table creation -> child creation and assignment -> parent level closing:
 t=sgxTable(-1, 10,10, 4,4, 6) 
b=sgxButton(-1, 4,4, 100,20, "button")
sgxCellAssign(0,0, b)
sgxCloseLevel()
or if you need to create childs later then like this..
table creation and parent level closing -> child creation and assignment with table parameter -> table refresh
 t=sgxTable(-1, 10,10, 4,4, 6) 
sgxCloseLevel()
b=sgxButton(-1, 4,4, 100,20, "button")
sgxCellAssign(0,0, b, t) ; <- table parameter specified
sgxRefresh(t)
..or like this..
table creation and parent level closing -> child creation -> setting the current parent -> cell assignment -> parent level closing
 t=sgxTable(-1, 10,10, 4,4, 6) 
sgxCloseLevel()
b=sgxButton(-1, 4,4, 100,20, "button")
sgxSetCurrentParent(t)
sgxCellAssign(0,0, b)
sgxCloseLevel()

Parameters:

i
column. (starting with 0)
k
line (starting with 0)
id
ID of a valid and existing sgx element or 0 if you want to clear the cell. the x/y-position of that element will be overwritten according to the position in table. the w/h dimensions of the element might be overwritten according to the table style.
table
-1 (default) if the current parent should be used as the table. otherwise specify the id of the table you want to assign to.

Top, Back


sgxSetKeyboardLayout(layout = #sgxKeyLayQwerty, keystrokeDelay_1 = 280, keystrokeDelay_2 = 40)

configure keyboard layout and keystroke delay used by sgxEdit elements (via sgx_keyboardEdit).
when using qwerty layout the characters '<', '>' (angle brackets) and '|' (pipe) can be accessed via 'alt-gr' + ',' / '.' / '-' (comma, dot and hyphen).

Parameters:

layout
#sgxKeyLayQwerty (default) for qwerty / US keyboard layout. #sgxKeyLayQwertz for qwertz / DE
keystrokeDelay_1
the keystroke delay after a first key-push in milliseconds (default 280)
keystrokeDelay_2
the keystroke delay for continuous key-push in milliseconds (default 40)

Top, Back


sgxLoadDesign(design.s = "lowbudget", basecolor = -1)

loads a design.
returns the loaded design or 0 if loading fails.
you don't necessarily need the return value, but you can store it for later use with sgxSetDesign in which case an integer variable is sufficient.
if you want to access structure fields of the design you should use a pointer of type sgxS_Design as variable.
if you call this procedure before you opened a screen, make use of sgxSetDimensions.

Parameters:

design
the path / directory that contains the design images, or "lowbudget" (default) for an instant design
basecolor
basecolor to be used for the design, or -1 (default) to use the color as found in the image data. 'lowbudget' will be fully colored. file-designs only support this for color of text and thin borders.

Top, Back


sgxRefreshDesign(*design.sgxS_Design)

refresh the design. i.e. after you changed the basecolor of the design. the images will be regenerated / reloaded from disk.

Parameters:

*design
pointer to a valid design

Top, Back


sgxCursor(id)

creates an sgx cursor element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.

Parameters:

id
ID for the new sgx element.

Top, Back


sgxButton(id, x, y, w, h, text.s, toggle = #sgxStateNone, sprNr = -1, x2 = 5, y2 = 5)

creates an sgx button element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
if a sprite is specified then you are responsible for the sprites lifetime, sgxFree will not free the sprite. also you should not free the sprite before you have freed the sgxButton, otherwise the sprite simply won't be displayed, but doesn't generate an error.
a togglebutton's state will change when leftclicked, or will be set to pushed if it is part of a radiogroup. rightclick behaviour can be configured via variable sgxRightclickUnset.
you can use sgxSetState with toggle buttons.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width
h
height
text
caption. use #LF$ / Chr(10) for line breaks
toggle
one of these values:
#sgxStateNone (default) for a standard button
#sgxStateOff for a toggle button
#sgxStateOn for a toggle button initialized as 'pushed'
sprNr
an optional PB #sprite to be displayed on the button. you can then also use -1 for the w/h-parameters to adjust the button to the size of the sprite.
x2
x-offset for the additional sprite
y2
y-offset for the additional sprite

Top, Back


sgxCheckbox(id, x, y, w, h, checked = #sgxStateOff, text.s = "", align = #sgxAlignCheckboxTextRight)

creates an sgx checkbox element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.

the specified position and size will define the knob. the overall size including the label will be stored in the fields w2 and h2. the fields x2 and y2 store the display position of the elements sprite (the visual size including the label) relative to the knob position. with #sgxAlignCheckboxTextLeft for example the label will start on screen at (x+x2),(y+y2) where x2 will be negative and y2 will be negative if the text is larger than the knob height.

a checkbox's state will change when leftclicked, or will be set to checked if it is part of a radiogroup. rightclick behaviour can be configured via variable sgxRightclickUnset.
you can use sgxSetState with this element.

Parameters:

id
ID for the new sgx element.
x
knob x-position relative to parent element
y
knob y-position relative to parent element
w
knob width
h
knob height
checked
#sgxStateOff (default) for unchecked or #sgxStateOn for checked
text
label
align
can be #sgxAlignCheckboxTextRight to have the label on the right (default), or #sgxAlignCheckboxTextLeft to have it on the left.

Top, Back


sgxScrollbar(id, x, y, w, h, w2, h2, max, state = 0, style = 0)

creates an sgx scrollbar element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
if height is greater than width, the scrollbar will be vertical, otherwise horizontal.
you can use sgxSetState and sgxSetScrollMax with this element.
note that for example for a scrollbar length of 10 pixel and a max state value of 100 you will only be able to receive every 10th state.
likewise for a scrollbar length of 100 pixel and a max state value of 10 you will only receive state changes every 10th pixel.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width (bar)
h
height (bar)
w2
width (knob)
h2
height (knob)
max
maximum possible scroll state (minimum is 0). this must be greater than 0 and will be corrected to 1 automatically if necessary.
state
initial state (default is 0)
style
possible values (you can combine flags with '|' (bitwise OR)):
0 (scrollbar default)
#sgxStyleGrid: draws a pseudo-grid.
#sgxStyleReverse : the state 0 will be at the left for horizontal and at the top for vertical scrollbars per default. by specifying the reverse flag the 0 state will be at the other end of the scrollbar.

Top, Back


sgxTrackbar(id, x, y, w, h, w2, h2, max, state = 0, style = #sgxStyleGrid)

creates an sgx trackbar element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
if height is greater than width, the trackbar will be vertical, otherwise horizontal.
you can use sgxSetState and sgxSetScrollMax with this element.
note that for example for a trackbar length of 10 pixel and a max state value of 100 you will only be able to receive every 10th state.
likewise for a trackbar length of 100 pixel and a max state value of 10 you will only receive state changes every 10th pixel.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width (bar)
h
height (bar)
w2
width (knob)
h2
height (knob)
max
maximum possible scroll state (minimum is 0). this must be greater than 0 and will be corrected to 1 automatically if necessary.
state
initial state (default is 0)
style
possible values (you can combine flags with '|' (bitwise OR)):
0
#sgxStyleGrid: draws a pseudo-grid (trackbar default)
#sgxStyleReverse : the state 0 will be at the left for horizontal and at the bottom for vertical trackbars per default. by specifying the reverse flag the 0 state will be at the other end of the trackbar.

Top, Back


sgxEdit(id, x, y, w, h, text.s = "", maxLines = -1)

creates an sgx edit element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
this is for user editable text only. for static labels use sgxText.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width
h
height
text
inital text. use #LF$ / Chr(10) for line breaks
maxLines
you can limit the amount of lines that can be entered by the user. use -1 (default) to not limit the amount of lines.

Top, Back


sgxWin(id, x, y, w, h, text.s = "", style = 0)

creates an sgx window element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
this element will be the parent for new sgx elements until you call sgxCloseLevel or until you create another parent element.

a window's state can be changed via the functions sgxPresentWin, sgxMinimizeWin, sgxRestoreWin, sgxCloseWin and can be inquired by checking the 'state' field for #sgxWinState.. values.
a closed window does not exists anymore and thus has no state. use the macro sgx() without structure field access to test the vailidty in that case.

you can use sgxPresentWin directly after sgxCloseLevel to present the window instead of showing it immeditately.
if you want the window to be created hidden, use sgxSetShow (see notes about child visibility) to hide the window after you finished the creation with sgxCloseLevel. you can then use sgxPresentWin later to show the window.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width
h
height
text
caption in titlebar. no text will cause the window to have no titlebar. use a space for an empty titlebar.
style
0 (default)
#sgxStyleResizable to make the window resizable via mouse.

Top, Back


sgxSpriteGadget(id, x, y, sprNr)

creates an sgx sprite container and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
you are responsible for the sprites lifetime, sgxFree will not free the sprite. also you should not free the sprite before you have freed the sgxSpriteGadget, otherwise the sprite simply won't be displayed, but doesn't generate an error.
you can use sgxSetState with this element.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
sprNr
a valid PB Sprite number, or 0. you can change the sprite via sgxSetState.

Top, Back


sgxArea(id, x, y, w, h)

creates an sgx area container and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
use sgx area elements to get mouse events without using any visuals.
areas dont't move up in z-order when clicked as other types do but other elements may move in front of an area. you can use sgxMoveOnTop to move it up manually if needed.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width
h
height

Top, Back


sgxTip(id, text.s)

creates a tooltip for an sgx element.

Parameters:

id
ID of a valid and existing sgx element
text
inital text of the tooltip. use #LF$ / Chr(10) for line breaks

Top, Back


sgxCombo(id, x, y, w, h, text.s = "")

creates an sgx combo element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
you can use sgxSetState with this element.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width
h
height
text
the possible entries separated by #LF$ / Chr(10)

Top, Back


sgxText(id, x, y, w = -1, h = -1, text.s = "", style = 0, margin = 3, textalign = #sgxAlignTextLeft, wordwrap = #False)

creates an sgx text element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
this is for static labels only. for user editable text use sgxEdit.
take in consideration that changing the text via sgxSetText will cause an element refresh, including drawing of design images as well as drawing of text onto the element's sprites, possibly also recreation of sprites if the size changes too. this will have an impact on performance, so don't take it lightly by changing it's text every frame for example.

Parameters:

id
ID for the new sgx element.
x
x-position relative to parent element
y
y-position relative to parent element
w
width. -1 (default) will adjust width to textwidth
h
height. -1 (default) will adjust height to textheigt
text
inital text. use #LF$ / Chr(10) for line breaks
style
with #sgxStyleThin the element will have a frame. #sgxStyleHover will cause it to have a mouseover effect. you can combine flags with '|' (bitwise OR), or use #sgxStyleHoverThin.
margin
space between text and border
textalign
one of these values:
#sgxAlignTextLeft (Default)
#sgxAlignTextRight
#sgxAlignTextCenter
#sgxAlignTextJustifySpaces (text justified per word)
#sgxAlignTextJustifyCharacters (text justified per character)
wordwrap
#False (Default), #True for automatic word wrap. works only if width (parameter w) is not set to -1.

Top, Back


sgxTable(id, x, y, columns, lines, margin, style = #sgxStyleGrid)

creates an sgx table element and returns it's ID.
the notes on sgxNew apply to return value and parameter 'id'.
this element will be the parent for new sgx elements until you call sgxCloseLevel or until you create another parent element.
use sgxCellAssign to place elements in the table, sgxCellId and sgxCell to access the cell elements.
each column will be as wide as the widest element in it.
each line will be as high as the highest element in it.
the size of the table will adapt to the sum of column widths / line heights. child elements of the table might not be completely refreshed until table creation is finished with sgxCloseLevel.

the parameters 'columns' and 'lines' specify the amount, so cell indices will range from 0 to amount-1. it does not necessarily hurt to oversize these dimensions if you're not shure how big you need the table to be later. each cell will need 4 bytes of memory, no matter if assigned or left empty and each colum as well as each lines needs additional 4 bytes of memory.

big tables with a lot of elements, possibly also subtables and especially in combination with #sgxStyleFitCellW and/or #sgxStyleFitCellH can impact performance if cell elements need to be refreshed often since this could cause refresh of other cell elements and the table itself. using #sgxStyleNoBG will also make a table refresh faster.
tables are desinged to be a quick way for simple layouts and in some cases it might be better to position, resize and refesh elements on you own without using a table.

Parameters:

id
ID for the new sgx table element.
x
x-position relative to parent element
y
y-position relative to parent element
columns
amount of maximum columns (see notes above)
lines
amount of maximum lines (see notes above)
margin
space between cells
style
possible values (you can combine flags with '|' (bitwise OR)):
0
#sgxStyleGridV : draw vertical grid lines
#sgxStyleGridH : draw horizontal grid lines
#sgxStyleGrid (default) : draw vertical and horizontal grid lines
#sgxStyleFitCellW : width of cell elements will be overwritten according to column width except for vertical scrollbars/trackbars, checkboxes and sgxText elements with automatic width adjustment.
#sgxStyleFitCellH : height of cell elements will be overwritten according to line height except for horizontal scrollbars/trackbars, checkboxes and sgxText elements with automatic height adjustment.
#sgxStyleNoBG : no background / only cells will be visible. (this will disable the grid flags)

Top, Back


sgxRefreshAll()

refresh all existing sgx elements, if you modified the design for instance.

Top, Back


sgxRefresh(id, mode = #sgx_refreshNormalWithTip)

refresh an sgx element.

Parameters:

id
ID of the sgx element to be refreshed.
mode
#sgx_refreshNormalWithTip : normal refresh (including sgx-tip).
#sgx_refreshOnlyTip : only the sgx-tip will be refreshed.
#sgx_refreshNormalWithChildsOfTables: normal refresh, but includes childs of tables.
#sgx_refreshSkipTableCheckboxRedraw : skip redraw for checkboxes created in tables.
#sgx_refreshEditMouseclickCursor : for edit elements: update the character textpos from the current cursor pixel position (as opposed to other way round). used when positioning cursor by mouseclick.
#sgx_refreshEditMousewheelScroll : for edit elements: disable the correction of textalign/scrollpos if cursor is outside clientarea. used when scrolling by mousewheel.

Top, Back


sgxExamine(mousex = -1, mousey = -1)

process actions / events and update the field data of all sgx element.
it returns the ID of the sgx element that is hovered by the mouse, or -1 if the mouse isn't hovering an element.
you can pass mouse coordinates if needed (for instance if you have self-calculated accelerated mouse movement). otherwise sgx will simply inquire the PB mouse library commands.

Parameters:

mousex
(optional)
mousey
(optional)

Top, Back


sgxDisplay()

display all sgx element on screen. only DisplayTransparentSprite() is used.

Top, Back


sgxDisplayCursor()

display the sgx mouse cursor on screen. under normal circumstances you don't have to call this function.
usefull if you want to overdraw/display something after you called sgxDisplay() but still want the mouse cursor to be visible, so you can redraw the cursor with this function after your drawing operations.

Top, Back


sgxDisplayID(id)

display an sgx element on screen. only DisplayTransparentSprite() is used.

Parameters:

id
ID of the sgx element to be displayed

Top, Back