New menu editing
the new UI is not provided by default, to access it, you will need to compile sandbox with -DNEWGUI
Windows Users
using codeblocks follow these steps after opening the project
- click on project
- click on build options
- click on defines
- type -DNEWGUI in the box that appears
Linux Users
users using codeblocks should follow the above steps, people using the Makefile follow these
- open the desired makefile in a text editor
- add -DNEWGUI into the DEFINES string
- make clean && make install
OSX
???
Contents
- 1 How it works
- 2 Commands
- 3 Elements
- 3.1 BorderedImage
- 3.2 Button
- 3.3 Clipper
- 3.4 CroppedImage
- 3.5 Conditional
- 3.6 ConditionalButton
- 3.7 Filler
- 3.8 Image
- 3.9 List
- 3.10 Offsetter
- 3.11 Rectangle
- 3.12 ScrollBar
- 3.13 ScrollButton
- 3.14 Scroller
- 3.15 SlotViewer
- 3.16 Spacer
- 3.17 StretchedImage
- 3.18 Table
- 3.19 Tag
- 3.20 Text
- 3.21 TextEditor
- 3.22 Toggle
How it works
Forks
Each fork represents a state of the element. If an element supports 2 or more forks, it reserves the first few (dependent on he amount of forks) children for the different states. For example you have a uibutton which has 3 forks, the first 3 children are used to solely represent its states. If we were to give it 4 children, and then hover over the button, child #2 and child #4 will be drawn, this is demonstrated below. A rule of thumb is to make the absolute minimum amount of children for an element the amount of forks it has.
uibutton [echo "Hello World"] [ uiimage "data/hud/2.1/icons/action.jpg" .05 .05 //shown when idle uiimage "data/hud/2.2/icons/action.jpg" .05 .05 //shown on hover uiimage "data/hud/2.3/icons/action.png" .05 .05 //shown on click/select uiimage "data/hud/blackfog/icons/action.png" .02 .02 //always shown ]
Siblings
The more obvious definition is for elements to be declared next to each other to be siblings. Not quite so, the relationship can be one way as a parent is also considered a sibling for lookup purposes, although a child is not.
This example is a standard scrolling container, uiscroll requires a uiscrollbar sibling to determine offsets and although not necessary, uiscrollbar works best with a uiscrollbutton child.
uiscroll .94 1 [ ... ] uiscrollbar .06 1 [ .... uiscrollbutton [ ... ] ]
Children
The obvious definition once again, elements defined in the children argument of another element. Almost all newui elements allow additional children to be spawned. Similar to siblings, any children of the children (as well as their respective children) also also counted as children of the current element. Children are a very important concept with this ui system as they are required for many of the elements to operate correctly. Remember elements need as least as many children as there are forks. This is demonstrated in the examples above.
States
Each fork is reached by the element exhibiting a certain state. You can find more detailed information on the available states for each element in the element's respective section. This area just discusses some of the more common states and how they are reached.
For items that utilise mouse based interactivity
- Idle - when your cursor is not hovering over the element, nor is it selected
- Hovering - when your cursor hovers over the element without clicking it
- Selected - when you click the element, you do not necessarily have to be hovering over it
For items with a conditional
- True - provided conditional evaluates to true
- False - absence of conditional or provided conditional evaluates to false
Remember to place the conditionals inside [] blocks, ie
uicond [= $cond 1] [ ... ]
Creating
When making menus or other miscellaneous UIs through this, you should place the showui command within an alias named showMYMENU, where MYMENU is substituted for the name of the menu. For example...
showMYMENU = [ showui MYMENU [ ... ] ]
Commands
hideui
- Arguments: Name
Hides the UI which matches the name
replaceui
- Arguments: Name Tag Children
within the named UI, it finds the tag which matches the provided name replaces its children. Note that if these arguments are supplied as a child to one of the elements, it'll be ignored.
showui
- Arguments: Name Children On-Hide
Creates a UI named Name which contains the provided children. The On-Hide script (if provided) is executed when the UI is closed
uialign
- Arguments: X Y
both arguments can be one of -1, 0 or 1. -1 refers to the top left and 1 to the bottom right. For example, uialign 1 0 will align things to the right. Note this only applies to its parent object. and only has a visible effect if there's space to move.
uialtimage
- Arguments: Image
Replaces the image of the prior element with this one, should it fail to load. It only works if its parent utilises an image and is the first child!
uiclamp
- Arguments: Left Right Bottom Top
This will cause the parent's edges to snap to the boundaries you provided true values for. It should be noted that as a child these boundaries are defined by it's parent.
For example, uicolor here will utilise all the available space from uifill
uifill .4 .4 [ uicolor 1 1 1 1 0 0 [uiclamp 1 1 1 1] ]
Elements
NOTE: these names of the classes do not necessarily correspond to the names of the commands to call them. if you want information of a specific command, please use ctrl-F to find it
BorderedImage
- Arguments: Image TexBorder ScreenSize Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uiborderedimage
- See Also: CroppedImage Image StretchedImage SlotViewer
This turns the provided image into a border, or a frame. ScreenSize determines the border size and TexBorder determines a texture offset from which to create the borders. If the the literal provided to TexBorder contains a lowercase p somewhere after the number, it will be interpretted as pixels. Also note that without any children, only the corners will be rendered.
A handy tip for creating the children is to use uispace to offset them away from the border: ie uispace ScreenSize ScreenSize [children here]
Button
- Arguments: Action Children
- Forks: 3
- fork1: Idle
- fork2: Hovering
- fork3: Selected
- Siblings: None
- Children: None
- Provided By: uibutton
Clipper
- Arguments: X-Size y-Size Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uiclip
- See Also: Scroller
This is like Scroller, except you cannot scroll
CroppedImage
- Arguments: Image X-Size Y-Size X-Start Y-Start X-End Y-End
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uicroppedimage
- See Also: BorderedImage Image StretchedImage SlotViewer
For the *-Start and *-End arguments, if there's a p present somewhere after the number, it'll be interpreted as an amount of pixels instead of a percentage. You can enter whatever you want before or after the p, it will be interpreted as pixels as long a lower case p is present.
Conditional
- Arguments: Condition Children
- Forks: 2
- fork1: True
- fork2: False
- Siblings: None
- Children: None
- Provided By: uicond
- See Also: ConditionalButton Toggle
If you only want it to display stuff while false, use "uifill 0 0" as the true child. If you do not wish to have anything display in the false case, you can use uifill 0 0 or not provide a child.
ConditionalButton
- Arguments: Condition On-Select Children
- Forks: 4
- fork1: False any
- fork2: True idle
- fork3: True hover
- fork4: True select
- Siblings: None
- Children: None
- Provided By: uicondbutton
- See Also: Conditional Toggle
It should be noted this button is only selectable if the condition is true. If the condition is false clicking the button will not heed in any results.
Filler
- Arguments: X-Size Y-Size Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uifill
Use this if you want to create a UI without a backdrop
Image
- Arguments: Image W-Size H-Size Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uiimage
- See Also: StretchedImage CroppedImage BorderImage SlotViewer
List
- Arguments: Space Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uihlist uivlist
Space is the amount of padding between the contained elements. We generally recommend using this to create Children for a Scroller.
Offsetter
- Arguments: W-Offset H-Offset Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uioffset
it essentially moves the elements this much
Rectangle
- Arguments1: R G B A W-Size H-Size Children (uicolor)
- Arguments2: R G B W-Size H-Size Children (uimodcolor)
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uicolor uimodcolor
The difference between the two is that the first draws a solid rectangle, and the second draws one which modulates the colour of the UI.
ScrollBar
- Arguments: Image W-Size H-Size Children
- Forks: 5
- fork1: Idle
- fork2: Hovering over up/left arrow
- fork3: Selected up/left arrow
- fork4: Hovering over down/right arrow
- fork5: Selected down/right arrow
- Siblings: Scroller
- Children: ScrollButton
- Provided By: uihscrollbar uivscrollbar
ScrollButton
- Arguments: Children
- Forks: 3
- fork1: Idle
- fork2: Hovering
- fork3: Selected
- Siblings: None
- Children: None
- Provided by: uiscrollbutton
Scroller
- Arguments: W-Size H-Size Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uiscroll
For most cases, List and Table elements should be used to create the content inside. It should be noted without a ScrollBar it is practically the same as a Clipper.
SlotViewer
- Arguments: Slot W-Size H-Size Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uiviewslot
Spacer
- Arguments: X-padding Y-Padding Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uispace
uispace places the padding around its children, so the space consumed is essentially twice as much as you tell it to. This is useful for getting the elements away from the edges.
StretchedImage
- Arguments: Image W-Size H-Size Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uistretchedimage
- See Also: Image BorderedImage CroppedImage
Table
- Arguments: Columns Padding Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uitable
Should you exhaust all the columns, the table will start afresh on a new row. If you intend to have a bunch of items span across and down the screen in a constant grid, we recommend using this to generate items for a Scroller element.
Tag
- arguments: Name Children
- forks: 0
- siblings: None
- children: None
- provided by: uitag
replaceui can be used to replace the contents of a tag
Text
- Arguments1: Text Size Children (uitext)
- Arguments2: Text Size R G B Children (uicolortext)
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uitext uicolortext
TextEditor
- Arguments: Name Length Height Scale InitialValue Keep Filter Children
- Forks: 0
- Siblings: None
- Children: None
- Provided By: uitexteditor
Name refers to a unique name for the editor. Any editor with a matching name edits the same items.
Length and Width state how many characters wide and how many characters high the field is.
If Keep is true, focus is not lost should the mouse move away from the field.
Filter is a collection of characters. Any characters within this list can't be used. for example "aeiou" will prevent the use of vowels.
Toggle
- Arguments: Condition On-Select Split Children
- Forks: 4
- fork1: false idle
- fork2: false hovering
- fork3: true idle
- fork4: true hovering
- Siblings: None
- Children: None
- Provided By: uitoggle
- See Also: Conditional ConditionalButton
We would recommend using this to create the likes of checkboxes and tabs. The action is executed regardless of whether or not the condition is false, unlike uicondbutton.