Revision as of 01:28, 27 January 2011

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

???

How it works

It should be noted that even we are still trying to figure out how it works.

Forks

Each fork represents a state, or even a combined state. Each one of these corresponds to a child. Any additional children are always interacted with and rendered.
For example, if you have an element with 2 forks, depending on its state, it'll either use the first child or the second child. If any additional children are provided, they will always be present.
In this below example we declare a uibutton element with 4 children. uibutton has 3 forks, so it'll choose from the first 3 children depending on its state. "data/hud/2.1/icons/action.jpg" will be drawn when idle, "data/hud/2.2/icons/action.jpg" will be drawn when hovered over and "data/hud/2.3/icons/action.jpg" will be drawn if it's selected. "data/hud/blackfog/icons/action.jpg" will always be drawn.


 uibutton [echo "Hello World"] [
   uiimage "data/hud/2.1/icons/action.jpg" .05 .05
   uiimage "data/hud/2.2/icons/action.jpg" .05 .05
   uiimage "data/hud/2.3/icons/action.png" .05 .05
   uiimage "data/hud/blackfog/icons/action.png" .02 .02
 ]

Siblings

When looking for a sibling item, the element in question first looks at its parent, and then it's parent (etc). Siblings elements are declared alongside the element, or as its parent. In this example, uiscroll and uiscrollbar are declared as siblings and uiscrollbutton is declared as a child of uiscrollbar.


 uiscroll .94 1 [
   ...
 ]
 uiscrollbar .06 1 [
   ....
   uiscrollbutton [
     ...
   ]
 ]

Children

When searching for a specific child element, the element searches its children and then its children. Simply, child elements are defined as part of its children. In the above example, uiscrollbutton is declared as a child of uiscrollbar.

States

for items that require 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 - conditional evaluates to true
False - 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]
 ]

<code>

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 idle
 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.

@@ Line 11: / Line 11: @@
 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 CXXFLAGS string
+* add -DNEWGUI into the DEFINES string
 * make clean && make install

Difference between revisions of "New menu editing"

Revision as of 01:28, 27 January 2011

Contents

How it works

Forks

Siblings

Children

States

Creating

Commands

hideui

replaceui

showui

uialign

uialtimage

uiclamp

Elements

BorderedImage

Button

Clipper

CroppedImage

Conditional

ConditionalButton

Filler

Image

List

Offsetter

Rectangle

ScrollBar

ScrollButton

Scroller

SlotViewer

Spacer

StretchedImage

Table

Tag

Text

TextEditor

Toggle

Navigation menu

Search