2.5 PANEL definition

2.5    PANEL definition

Any PANEL definition must be placed in the GUI section and defines a controls panel (forms) to be used in the game.

 

GUI section’s syntax is as follows (square brackets indicate optional parts):

PANEL panelId [VERSION OF parentPanelId] 

[BUTTON definition | CR definition | MAP definition | TEXTBOX definition | LABEL definition | DROPDOWN definition | DELETE spec ]

[more control definitions…]

 

The VERSION OF tag may be added to build a modified version of an existing panel, so that you just add additional controls, or delete existing ones.

 

Parameters Meaning
panelId

Identifier of the panel (mandatory)

If the panelId identifier represents an existing panel, the new definition will replace the existing one.

Note: “default“, “chat“, “connecting” and “exiting” are IDs of pre-defined panels.
default” is the panel to be used by default at the game’s startup and in controls’ quick definitions.
chat” is an alternate, simplified set of commands which can be used for chatting purposes, by means of the SetPanel instruction (see section 3.12.25, in the SmallBasic reference).

connecting” is the panel to be used while connecting.

exiting” is the panel used when a “Save and Exit” command is used.

parentPanelId (Optional) Identifier of an existing panel from which commands should be imported.

 

As it should be clear, a PANEL tag just specifies the PANEL’s id for later reference, and acts as a container for the controls’ specifications. For more information about them, see 2.5.2How PANELs work.

2.5.1    Pre-defined PANELs

DimensioneX has got a number of pre-defined PANELS which, in turn, consist of pre-defined controls.

Please remember that all defined PANELs can be inspected by using the DimensioneX Administrator’s screen, selecting Snapshot and then Panels.

 

panel id what is it? built-in control IDs
Default It is the panel used normally – all commands available. go, look, use, use2, _sep4, open, close, pick, drop, _sep9, search, hide, put, give, _sep14, enter, exit, _sep17, _sep18, txtBox, say, _sep21, _sep22, clear, help, _sep25, save,savexit, logout
Chat It is a simplified panel, useful for chatting and little else

go, look, _ctr2, _sep3, txtBox, _sep5, _sep6, use, _sep8, _sep9, help, savexit, logout

 

Connect Initial connect screen go, look, lbl0, username, _sep4, lbl1, skin, _sep7, lbl2, audio, _sep10, lbl3, music, _sep13, lbl4, screensize, _sep16, _sep17, help, login, lbl5, lbl6
Connecting It is used by the system when connecting with a saved profile go, look, lbl0, _sep3, pass, _sep5, _sep6, login, _sep8, _sep9, startscratch, cmd, _sep12, _sep13, return, _sep15, _sep16, help
Exiting It is used by the system when doing “Save and Exit” go, look, lbl1, txtBox, _sep4, _sep5, savexit, _sep7, return, _sep9, help

 

Note:

  • _sep*** in the above table are separators (line breaks).
  • Labels for the built-in controls of the pre-defined PANELs are directly taken from the msgs_xxx.properties language file.
  • pre-defined controls (look, open, etc…) will trigger pre-defined EVENTs. Currently there’s no documentation on this. So, to know exactly which EVENT is triggered by each command, you should simply use the command and then look on the log file to see which EVENT is triggered (loof for “world.fireEvent”).

2.5.2    How PANELs work

  • Each game (or WORLD) at startup is initialized so that it uses the default
  • Each connecting player may have a player-scpecific commands panel. However, this player-specific commands panel is not set by default.

 

When a player is in the game, the controls he or she sees are determined by the following:

  • player-specific commands (optional, as for point b above)

plus (+)

  • room-specific commands (optional). If these are missing, then the commands from the world’s current PANEL is used (normally the default one as specified in point a above).

 

The world’s current panel can be changed via the SetPanel instruction (see SmallBasic guide, below)

Also the player’s specific or room’s specific panels can also be changed via the setPanel instruction.

The combination of specific, and WORLD-wide panels gives the game programmer a great flexibility and power.

2.5.3    BUTTON definition

BUTTON defines a command button inside a PANEL definition.

The syntax depends on what button you need, as follows:

 

Syntax #1, for standard buttons:

BUTTON id,”Label”,”ToolTipText”, Event [,EventModel]

 

Syntax #2, for ICON-enhanced buttons:

BUTTON id,”BalloonText”,”ToolTipText”, Event [,EventModel]

     ICON src

 

Syntax #3, for IMAGE buttons:

BUTTON id,”BalloonText”,”ToolTipText”, Event [,EventModel]

     IMAGE [widthxheight] src

 

Syntax #4, for quick import from default panel

BUTTON id

[ICON src]

 

Syntax #1 is the standard one.

 

Syntax #2 is a the recommended one. You specify an icon to be shown starting from the upper-left corner of the button. The icon is typically a 16×16 transparent GIF image (but you can actually use imges of any size and type depending on the effect you want to achieve). This syntax will cope with multiple languages and colours.

 

Syntax #3 adds a line for specifying the buttons’ IMAGE. Consult 2.10 – IMAGE at page 49 for more information on the IMAGE definition.

 

Syntax #4 is also said “quick definition”. It is used to quickly reference a standard, existing BUTTON control which is present in the “default” commands PANEL without having to re-define it. The commands look, by example, must be included in all panels so this syntax can be used to quickly do the job. Also the command logout, savexit, help may be useful to include.

You can also specify an ICON tag so that an icon is added to standard commands.

 

 

Parameters Meaning
Id Identifier of the button (mandatory)
Note
: The following Ids have a special meaning and are automatically dealt with by the DimensioneX Javascript client. Don’t use these ones if you would like to implement different, custom commands:look, go, logout, savexit, return, rotate, use, use2, drop, pick, put, give, say, search, hide, clear, rotr, rotl

You can use the above, however, to change the look of the buttons but you won’t be able to change the command’s standard behaviour.

Label Text of the button as it will appear on the command panel. Double quotes recommended.
BalloonText Text which will appear in the yellow balloon hints when pausing with the mouse on an IMAGE button’s surface. Same as for Label.
ToolTipText

Tip text for the toolbar hints. Double quotes are mandatory.

The triple dots are automatically handled by the client and substituted with actual object names. A typical Tip Text are

“Attack …”

“Trade … with …”

“Give … with …”

and so on.

Event ID of for the event or full function call to be triggered when the command is used. If you specify parameters separated by commas, you MUST place the code between double quotes.
EventModel

Describes what parameters the command uses and how they are mapped into the owner/target variables according to the DimensioneX avent model. Values can be one of the following:

(none) : no parameters

O : 1 object parameter (owner)

OO : 2 object parameters (owner, target)

T : 1 text parameter (target)

TO : 1 text parameter, 1 object parameter (target, owner)

 

Here is an example, which defines a control which rolls a dice, and includes the code for the associated EVENT to exploit this new custom command:

 

GUI

PANEL default

BUTTON create, “Create Object”, “Create Object!”, onCreate

BUTTON destroy, “Destroy Object”, “Destroy Object!”, onDestroy

      BUTTON rolldice, “Roll Dice”, “Roll Dice!”, onRollDice

BUTTON look

BUTTON logout

END_GUI

 

SCRIPTS

 

EVENT onRollDice

      nr = rndInt(6)

      Speak SYS,$WORLD,$AGENT.name + ” has rolled the dice and the result is ” + nr

 

END_SCRIPTS

 

Another example, showing how a full function call can be used in Event. Here, the doAffinity sub is used to handle all four buttons, in fact the working logic is depending on the value of the four parameters.

 

PANEL paffinity

BUTTON waterplus, “+”, “Command”, “doAffinity(1,0,0,0)

BUTTON water, “Water”, “Water”, helpAffi

IMAGE 32×32       elem1.gif

LABEL ” Water”

BUTTON waterminus, “-“, “Command”, “doAffinity(-1,0,0,0)

LABEL “<BR />”

BUTTON earthplus, “+”, “Command”, “doAffinity(0,1,0,0)

BUTTON earth, “Earth”, “Earth”, helpAffi

IMAGE 32×32       elem2.gif

LABEL ” Earth”

BUTTON earthminus, “-“, “Command”, “doAffinity(0,-1,0,0)

LABEL “<BR />”

BUTTON windplus, “+”, “Command”, “doAffinity(0,0,1,0)

BUTTON wind, “Wind”, “Wind”, helpAffi

IMAGE 32×32       elem3.gif

LABEL ” Wind”

BUTTON windminus, “-“, “Command”, “doAffinity(0,0,-1,0)

LABEL “<BR />”

BUTTON fireplus, “+”, “Command”, “doAffinity(0,0,0,1)

BUTTON fire, “Fire”, “Fire”, helpAffi

IMAGE 32×32       elem4.gif

LABEL ” Fire”

BUTTON fireminus, “-“, “Command”, “doAffinity(0,0,0,-1)

LABEL “<BR /><BR /><INPUT TYPE=hidden NAME=affi VALUE=1>”

BUTTON dothis,”Done”,”Command”, doCommand

 

Sub doAffinity(e1,e2,e3,e4)

‘Event code…

End_Sub

2.5.4    CR definition

CR defines a carriage return inside a PANEL definition. The syntax is simply as follows:

 

CR

2.5.5    MAP definition

MAP defines a map box inside a PANEL definition. The syntax is simply as follows:

 

MAP

 

The map image to be displayed must be defined in the GUI section by means of the MAP tag and can be changed according to any room by using the room’s map attribute.

2.5.6    TEXTBOX definition

TEXTBOX defines a text box inside a PANEL definition. The syntax is as follows:

 

TEXTBOX [id]

 

The id is optional and will be returned as a key in the input( ) set. If omitted, ir defaults to “txtBox”

2.5.7    LABEL definition

LABEL defines a label inside a PANEL definition. The syntax is simply as follows:

 

LABEL “free text

 

Note: HTML code can be inserted inside double quotes. This element is indeed very powerful as it can be used to create very special panels, provided you have understood how the Javascript in the player’s client works.

2.5.8    DROPDOWN definition

DROPDOWN defines a drop-down list inside a PANEL definition. The syntax is:

 

DROPDOWN id,Set,Default [,WorkingModel]

 

Parameters Meaning
Id Identifier of the control (mandatory)
Avoid conflicts with reserved (and other custom) control IDs
Set

Expression to be evaluated at run-time which must return a SET containing identifiers and decriptions or an ARRAY containing decriptions to be used for building the dropdown list.

You can use $OWNER to reference the player. For complex expressions you must enclose the expression between quotes, otherwise you will get an error.

Example:

“$OWNER.setChoices” is a valid expression,

$OWNER.setChoices will report that there is an unexpected dot.

Default

Expression to be evaluated at run-time which should (theoretically) be one of the Ids of the Set. If so, the corresponding element will be pre-selected.

Note: If Set will result in an ARRAY then this must be a zero-padded number of four digits.

Example : 0002 sets the second element of the array as the default.

You can use $OWNER to reference the player. For complex expressions you must enclose the expression between quotes, otherwise you will get an error.

WorkingModel

(Optional) Sets the working mode.

Possible values: AUTOSUBMIT

 

Note: In this release this setting will not produce any result. This functionality will be implemented in future releases.

2.5.9    DELETE specification

DELETE removes an existing control from the panel:

The syntax is:

 

DELETE id

 

Parameters Meaning
Id Identifier of the control to be removed (mandatory)

 

In the following example, we modify the connect panel so that it fits a horizontal frame:

 

PANEL connect VERSION OF connect

CR

DELETE _sep3

DELETE _sep4

2.6 PAGE definition
2.4 HOOKS definition

Leave a Reply

Your email address will not be published. Required fields are marked *