sgx.html.line1.gif
sgx a PureBasic screen gadget library
sgx.html.line1.gif
sgx.html.line1.gif
documentation
full reference

including
creating
handling
fields
example
designs
infos
sgx.html.line1.gif

Getting startet

this is a introduction to sgx which explains the general mechanics. after this you might want to see the examples in the directory 'sgxDoc\'. further there is a full reference (sgxDoc\sgxDocFull.html and a smaller reference (sgxDoc\sgxDoc.html) without sgx internals. the file _README.TXT in the base directoy contains further informations such a description of files and directories. for an on-screen demo see 'demo.exe' and maybe 'testFPS.pb'.

sgx.html.line1.gif

including sgx

first you would probalby simply include the single-file version of sgx 
XIncludeFile "sgx.pbi"
or the multi-file version 
XIncludeFile "sgx_.pbi"   ; will include all the other sgx_* files
the examples in the directory 'sgxDoc\' use a separate file ('_sgx_includer.pbi') to make it easier to switch between the two versions for all examples.

alternatively you could also just duplicate the sgx.pbi to let's say my_sgx.pb and start coding at the end of the file. that way, if you only use the design "lowbudget", this file would not have any dependencies for other include files or image files!

so you need at least the single sgx.pbi (or alternatively the sgx_* files). if you want to use designs other than "lowbudget" you would additionally need the directory containing the design images. you can use the script 'make.bat' to recreate a single-file version package in the directory 'sgx_build\', which only contains the files needed to simply use sgx (without tools and gimp files etc.). see _README.TXT for details.

a note about autocompletion:
autocompletion of sgx element structure fields works best with the multi-file version (if 'sgx_access.pbi' is not part of the project and not open in the editor). if you want to get complete autocompletion with the single-file version you may have to extract the sgx_access part and put it in a separate file.

after you opened a screen you must call sgxLoadDesign() at least once to initalize sgx. it returns a handle to the loaded design. 
; load a design from disk
mydesign1 = sgxLoadDesign(".\sgxDesigns\grey")

; "lowbudget" loads from a datasection
mydesign2 = sgxLoadDesign("lowbudget")
"lowbudget" does not need any image files and can have any color. some other designs come as files with the package.

sgx.html.line1.gif

sgx.html.up.gif creating elements

the last loaded design is used for new sgx objects, which you can create now. you can change the currently used design by calling sgxSetDesign(mydesign). 
sgxCursor(1)
sgxButton(2, 20,20, 100,25, "quit")
sgxSetDesign(mydesign1)
sgxButton(3, 20,50, 100,25, "button")
here 1, 2 and 3 are your choosen constant IDs of your sgx elements. if you want dynamic IDs then use -1 and catch the return value 
mybutton = sgxButton(-1, 20,20, 100,25, "toggle me", #sgxStateOff)
some sgx element types (like windows) can have childs. so you must call sgxCloseLevel() to create top-level objects again (or objects of the previous parent level). elements created in this block will automatically become childs of the window. 
sgxWin(4, 100,100, 200,180, "a window")
  sgxButton(5, 10,30, 80,20, "child")
sgxCloseLevel()
you can add a tooltip to any object (in this case a constant has been used to create the element). 
sgxTip(#buttonQuit,"exit"+#LF$+"demo")
note that this does not create a 'tip' element but rather sets a tooltip for our button element with the ID #buttonQuit.

sgx.html.line1.gif

sgx.html.up.gif handling elements

in your main loop use sgxExamine() to process user actions and sgxDisplay() to dispay the gadgets. 
  sgxExamine()
  ; ...
  sgxDisplay()
you access your elements by ID and you can detect valid objects by a nonzero value of the macro sgx(id): 
If sgx(2)
  Debug "id=2 is an existing and valid sgx object"
EndIf
you can inquire states of objects by fields: 
If sgx(2)\leftclick
  quit = 1
EndIf
those field accesses must only be applied with valid IDs

sgx.html.line1.gif

sgx.html.up.gif element fields

here are some commonly used fields. for details see the documentation of the gadget structure sgxS_GADGET. 
sgx(id)\leftclick    ; single fired event for mouse button click
sgx(id)\rightclick   ; 

sgx(id)\leftdown     ; continuously fired event for mouse button down
sgx(id)\rightdown    ; 

sgx(id)\leftup       ; single fired event for mouse button release
sgx(id)\rightup      ; 

sgx(id)\lefthold     ; hold event fired in intervals

sgx(id)\state        ; the current state of a checkbox or a scrollbar/trackbar etc (see structure description).

sgx(id)\text         ; a window's title, button's caption, edit's content, etc.
sgx(id)\type         ; a value of one of the #sgxType.. constants

sgx(id)\show         ; if #True then the element will be displayed and receives events, otherwise #False.
sgx(id)\disabled     ; 0 by default. 1 if the element is currently disabled.

sgx(id)\hover        ; continuously fired event if the mouse is hovering the element
sgx(id)\changed      ; single fired event if the element's state or the text/textpos of an sgxEdit etc. has changed.
sgx(id)\resized      ; single fired event if the size has changed

sgx.html.line1.gif

sgx.html.up.gif a complete example

(you may have to adapt the path in the include statement and in the second call of sgxLoadDesign()) 

XIncludeFile "sgx.pbi"

InitSprite()
InitMouse()
InitKeyboard()

win = OpenWindow(0, 1,1, 800,600, "..", #PB_Window_ScreenCentered)
OpenWindowedScreen(win, 0,0, 800,600)

; define some element IDs (always start with id 1)
Enumeration 1
  #cursor
  #buttonQuit
  #window
    #buttonChild
EndEnumeration

; load some designs. "lowbudget" can have any color.
design1 = sgxLoadDesign("lowbudget", RGBA($88,$66,$00,$dd))
design2 = sgxLoadDesign("sgxDesigns\grey")
If Not (design1 And design2)
  MessageRequester("error","can't load designs") :: End
EndIf

; create two elements
sgxCursor(#cursor)
sgxButton(#buttonQuit, 20,20, 100,25, "quit")

; change the design
sgxSetDesign(design1)

; create some other elements
mybutton = sgxButton(-1, 140,20, 100,25, "toggle button", #sgxStateOn)
sgxWin(#window, 100,100, 300,180, "a window")
  sgxButton(#buttonChild, 10,30, 100,20, "child element")
sgxCloseLevel()

; add a tooltip to the quit button
sgxTip(#buttonQuit, "exit"+#LF$+"demo")

Repeat
  ExamineMouse()
  ExamineKeyboard()
  
  ; proccess PB window events
  Repeat
    event = WindowEvent()
    If even = #PB_Event_CloseWindow
      quit = #True
    EndIf
  Until Not event
  
  ; update sgx events
  sgxExamine()
  
  ; process sgx events
  If sgx(#buttonQuit) And sgx(#buttonQuit)\leftclick
    quit = #True
  EndIf
  
  ; display all sgx elements
  sgxDisplay()
  
  FlipBuffers()
  ClearScreen($002222)
  Delay(5)
Until quit  Or  KeyboardPushed(#PB_Key_Escape)

sgx.html.line1.gif

sgx.html.up.gif about designs

a design has a directory containing some image files.
for example: '..\sgxDesigns\outdoor'

- BackgroundHover.png
- BackgroundNormal.png
- MouseCursor.png
- parts.png

the background pictures will be tiled to fill the areas they are drawn onto. 'MouseCursor' will be used for sgx elements of type #sgxTypeCursor. 'parts' contains the border images (4 corners and 4 sides for each state: normal, hover and pushed), and also the 2 states for the close buttons of windows (normal and hover) as well as the part displayed for checked checkboxed. the color found in the upper left corner (pixel 0,0) will be interpreted as to be used to seperate the elements in this image. the color found in the bottom left corner (pixel 0,imageHeight-1) will be the base-color of the design if nothing else is specified at sgxLoadDesign(). the elements should be more or less in order, separated by at least 1-pixel-thick rows and columns in the separating color. the images as well as the elements in the parts image can be of any size.

..\sgxDesigns\outdoor\parts.png (magnified) :

parts

sgx.html.line1.gif

sgx.html.up.gif additional informations

here is a quick list of usefull variables and macros/functions



sgx.html.up.gif