GUI Editor

From HEWIKI
(Difference between revisions)
Jump to: navigation, search
(→Starting the Editor)
(redesigning the page, making it easier to understand and get started using the GUI Editor)
Line 5: Line 5:
 
The GUIEditor allows for the creation of GUI Control Prototypes, in a WYSIWYG visual format. After a prototype has been created, a script can be written which creates nodes based on the prototype.  
 
The GUIEditor allows for the creation of GUI Control Prototypes, in a WYSIWYG visual format. After a prototype has been created, a script can be written which creates nodes based on the prototype.  
  
−
[[Image:GUI_tab-organizer_panel.png|right|GUI_tab-organizer_panel.png]]  
+
[[Image:GUIEditor Properties Panel.png|right|GUI Editor Properties]]  
  
−
<br>
+
<br>  
  
 
== Starting the Editor  ==
 
== Starting the Editor  ==
Line 15: Line 15:
 
In current versions, the GUI Editor is accessed by:  
 
In current versions, the GUI Editor is accessed by:  
  
−
*Opening the [[Organizer Panel]] and selecting the '''GUI XML''' tab  
+
*Opening the [[Organizer Panel]] and selecting the [[Organizer Panel#GUIXML_tab|GUIXML tab]]
 
**You may need to click on the arrows to find the tab at the far right  
 
**You may need to click on the arrows to find the tab at the far right  
 
**It may take a moment for prototypes to load  
 
**It may take a moment for prototypes to load  
 
*Choose a prototype to edit  
 
*Choose a prototype to edit  
−
*Double-click on the prototype to go into edit mode for it.  
+
*Double-click on the prototype to go into edit mode for it.
  
−
<br>
+
<br>  
  
−
== Create a New Prototype ==
+
== Using the Editor  ==
  
−
*In your [[Organizer Panel]] is a tab marked GUIXML. If you do not have the Organizer visible, select it from the [[Panels menu]].
+
The GUI Editor is used to modify the default value of a [[GUI Controls#GUI_Control_Base_Fields|GUI Control's fields]]. The value of these fields are stored in a client-side prototype which is generated from [[GUIXML]] files. These fields are edited in the [[Properties panel|Properties Panel]]. When a prototype is opened for editing the Properties Panel will automatically open.  
−
*Click the '''Create New''' link at the bottom of the GUIXML panel. This should open a window. It will have four inputs on it:
+
−
**'''Prototype Name'''
+
−
***This is the name of your window as it appears in the GUIXML tab. This namespace is shared amongst all GUI Control prototypes, so should be reasonably unique.
+
−
**'''Description'''
+
−
***This is a textual description of the purpose of the control, such as "Hero's Journey inventory window".
+
−
**'''Inherit From'''
+
−
***This is where you choose what base control/window to use to create your control.
+
−
***It is advised that you create one base window control, and inherit from it to create more specific types such as an inventory window.
+
−
**'''Class'''
+
−
***Similar to inheritance, it is advisable to create one base window class, and create new classes to inherit from that as necessary. For more information on creating a class, see the [[Dom editor|Dom Editor]]. You should ensure that any classes you create for GUI Controls use the '''guicontrol''' archetype, as opposed to '''data'''.
+
−
*Click the "Okay" button in the Window. The window will now be placed on the screen in its editable state.
+
−
**Whenever possible, try to coordinate with coworkers so that you are not creating a new prototype simultaneously, as only one client at a time can currently write to the XML .lst files.
+
−
*Note that the Properties Panel is now populated with the control's properties.
+
−
*If you have inherited from an existing prototype such as "_window", you might click on the "+" next to the name of your new window in the directory tree at the top section of the Properties Panel. Note that it has several child controls, some of which may have their own children. As you click on the name of each one, the Properties Panel reflects the [[GUIXML]] properties for it, and a different section of the created window is highlighted, to show which part you are dealing with.
+
−
**Only some properties may be changed on inherited children. For example, you can never change the '''name''' of an inherited control, nor can you change their order in their parent's children list. However, you can change many other useful properties, such as their layout (size, position, texture, color, et al) and script.
+
−
*Clicking on the name of the control that you created results in the entire control being highlighted in the viewport.
+
−
*Note that the selected control can be moved and resized, by dragging it around the screen.
+
−
*You can add new children to whatever control you have selected (caveat: GUILabel controls can not display children) by double-clicking the name of the desired child in the Organizer panel.  
+
−
**Controls are added to whichever control is currently selected in the directory tree.
+
−
**Any children associated with the new control's prototype are added as well.
+
−
**The newly added control will be automatically selected when added, so if you are adding multiple controls to the same parent, be sure to reselect it each time (this is easily done by right-clicking in the GUI Editor area).
+
−
 
+
−
<br>
+
  
−
== Appearance and Layout ==
+
When editing a GUI Control prototype the layout of the Properties Panel is similar to how it looks if a [[Model]] was selected except the listed properties are different and there is a GUI Control Hierarchy Tree View at the top of the panel. The properties can be displayed in two ways, Categorized and Alphabetical. The Categorized view will split the properties into the following collapsible sections: [[GUI Controls#Appearance|Appearance]], [[GUI Controls#Behavior|Behavior]], [[GUI Controls#Data|Data]], [[GUI Controls#Layout|Layout]], [[GUI Controls#Misc|Misc]] and [[GUI Controls#Presentation_States|Presentation States]]. The Alphabetical view will list all of the properties in alphabetical order.  
−
 
+
−
=== GUI Textures ===
+
−
 
+
−
Art for GUI Controls must be stored in the [[Repository]] in the form of a DirectDraw Surface (.DDS) file.  
+
−
 
+
−
If you will not be creating your own art, you can skip this next section, or bring it to the attention of those who will.  
+
  
 
<br>  
 
<br>  
  
−
==== Creating your own art ====
+
=== Appearance  ===
−
 
+
−
The first rule of creating your own art is: when in doubt, have an artist do it. However, should you not be an artist, and still find yourself with the need to create GUI art, read on.
+
−
 
+
−
I'm not going to go into a lot of detail regarding the creation of a new piece of art, and I'm going to assume you have a minimal working knowledge of Photoshop. The easiest way is to find art on Google Image Search, or use clip art or stock photography. You should avoid copyrighted images; it's possible to find royalty-free art, but this document is in no way going to address the legalities of what art may be used for what. Paste your art into Photoshop (or draw your own, if you prefer), and alter it as necessary (resizing, coloring, etc). Again, the specifics of this are way beyond the scope of this document. DDS files use the alpha channel to determine transparency, so you'll need to modify that as well.
+
−
 
+
−
[[Image:Photoshop7_create_new_channel.png|right|Photoshop7_create_new_channel.png]] Click the channels tab (or use Window-&gt;Channels), and you should see at minimum four channels marked RGB, Red, Green, and Blue. You may also see an Alpha 1 channel. If not, your next step is to create an alpha channel. Do this by clicking the third button at the bottom of the channels panel (left of the trash can, looks like a page with one corner peeled back). This should automatically create the Alpha 1 channel, if it did not already exist.
+
  
−
Now switch back to the Layers tab, and make sure that the layer which contains your piece of art is selected. Using the wand and/or lasso tools, select only the portions of your art that you want to be visible. Often, the easiest way to do this is to simply click outside of the art with the Wand tool, thus selecting all of the transparent pixels, and hit Control-Shift-I, to invert the selection. Viola, only your art is selected. If your art has transparent pixels inside of it as well, you will want to make sure that the Wand tool has its Contiguous box unchecked (which means that it will select ALL qualifying pixels on the layer, instead of ignoring those which are separated from your click location by nontransparent pixels).  
+
The [[GUI Controls#Appearance|Appearance]] section of properties controls how the GUI Control's texture is displayed to all of the state presentation properties as well as the <code>texture</code> property, which is the Fully Qualified Name (FQN) of the texture file in the [[Repository]].
  
−
Now switch back to the Channels panel, and select only the Alpha 1 channel. Your selection should still be only the space taken up by your piece of art. Alpha channels work on a greyscale to determine opacity, where black is completely transparent, and white is completely opaque, so go to Edit-&gt;Fill and fill the selected area with White. You can play with making the borders somewhat darker, or using a gradient, but if you're getting into that much detail, an artist should probably have been doing it in the first place, or you should have just skipped this whole section 'cause you already know it.  
+
[[Image:GUIProperties_Appearance.png|GUIProperties_Appearance.png]]
  
−
Three important notes on DDS files:
+
==== GUI Textures  ====
  
−
*The image's dimensions should each be a power of 2 (256x256, 512x512, etc). This is to ensure compatibility with certain older display adapters. You should use the smallest size file you can get away with, and place your art in the upper left corner...this lets you expand the file's dimensions later if necessary, without the need to relocate your existing art.  
+
Art for GUI Controls must be stored in the [[Repository]] in the form of a DirectDraw Surface (.DDS) or .PNG file. To assign a texture to be used by a GUI Control you can use the Texture Viewer accessible from a state presentation field or the texture field.  
−
*To save in the DDS format, your file must have a Background layer, and it must be visible, or the DDS plugin will report an Unsupported Format error.
+
−
*You must have a DDS plugin available to Photoshop. At the time of writing, this can be found in a utility package on nVidia's site at the bottom of [http://developer.nvidia.com/object/photoshop_dds_plugins.html this page]. The plugin itself is called dds.8bi, and should be placed in the base Plugins folder, wherever Photoshop is located.
+
−
 
+
−
Settings for saving a DDS file for use with HeroEngine:<br> [[Image:Dds_settings.png|Dds_settings.png]]
+
−
 
+
−
<br>
+
−
 
+
−
==== Making New Art Available ====
+
−
 
+
−
After you have your new art, you'll need to upload your new DDS file to the repository using the [[Repository Browser|Repository Browser]]. The DDS file needs to be uploaded to your GUI art folder.  
+
  
 
<br>  
 
<br>  
  
−
=== Presentation States ===
+
=== Presentation States ===
  
−
[[Image:Gui_editor_texture_viewer.png|right|Gui_editor_texture_viewer.png]] A GUI control's state presentation determines its appearance in various predefined states. There are five state presentations available to work with:  
+
A GUI control's [[GUI Controls#Presentation_States|State Presentation]] determines its appearance in various predefined states. There are five state presentations available to work with:  
  
 
*'''defaultStatePresentation''' - how the control appears when no other state applies
 
*'''defaultStatePresentation''' - how the control appears when no other state applies
Line 105: Line 60:
  
 
Note that GUILabel class controls are treated differently by their state presentations. Changing the color of a GUILabel's state presentation will actually affect the text of the label, not provide a background color. Adding a texture to a GUILabel-based control will do nothing of interest.  
 
Note that GUILabel class controls are treated differently by their state presentations. Changing the color of a GUILabel's state presentation will actually affect the text of the label, not provide a background color. Adding a texture to a GUILabel-based control will do nothing of interest.  
 +
 +
[[Image:StatePresentation Properties.png|Default state presentation properties]]
  
 
<br>  
 
<br>  
  
−
==== Texture Mapping in a state presentation ====
+
==== Texture Mapping in a state presentation ====
  
 
The size and position fields of a state presentation refer to the image specified by the control's texture field. If a control has no texture field declared, size and position will do nothing. Used in conjunction, these two fields determine the placement and size of a rectangular slice of the image, to be applied to the control. While state presentations may (and frequently will) use different areas of a .dds file to determine a control's appearance, they must all use the same texture file. You cannot have your hover states in one .dds file, and your disabled states in another. The texture viewer shown to the right can be pulled up by clicking in the '''texture''' field in the GUI Editor, or on any of the state presentation fields or subfields, with the exception of '''color'''.  
 
The size and position fields of a state presentation refer to the image specified by the control's texture field. If a control has no texture field declared, size and position will do nothing. Used in conjunction, these two fields determine the placement and size of a rectangular slice of the image, to be applied to the control. While state presentations may (and frequently will) use different areas of a .dds file to determine a control's appearance, they must all use the same texture file. You cannot have your hover states in one .dds file, and your disabled states in another. The texture viewer shown to the right can be pulled up by clicking in the '''texture''' field in the GUI Editor, or on any of the state presentation fields or subfields, with the exception of '''color'''.  
Line 119: Line 76:
  
 
Note that one approach taken by some art departments is to create their GUI art at double the intended size, to allow for less pixelization when a control is scaled. In a situation such as this, the state presentation dimensions would still follow the same procedure as with a normal-sized texture, as the size field of the control still dictates its displayed appearance. For example, an icon whose art is created at 128x128 pixels may still be displayed as a 64x64 icon, simply by setting its state presentation size to 128x128, and its actual size to 64x64.  
 
Note that one approach taken by some art departments is to create their GUI art at double the intended size, to allow for less pixelization when a control is scaled. In a situation such as this, the state presentation dimensions would still follow the same procedure as with a normal-sized texture, as the size field of the control still dictates its displayed appearance. For example, an icon whose art is created at 128x128 pixels may still be displayed as a 64x64 icon, simply by setting its state presentation size to 128x128, and its actual size to 64x64.  
 +
 +
[[Image:Gui editor texture viewer.png|400x500px|Texture Mapping in a state presentation]]
  
 
<br>  
 
<br>  
  
−
==== Color in a state presentation ====
+
==== Color in a state presentation ====
  
 
'''Color''', a complex field of type rgba, is most often used to set the background color of a control which has no texture applied to it. This simply fills the control with a solid color, such as the titlebar of the texture viewer to the right. If you are familiar with the 0 to 255 scale for RGB, rgba simply translates that into a float of range 0 to 1, with alpha (color.a) equating to completely transparent at 0, completely opaque at 1.  
 
'''Color''', a complex field of type rgba, is most often used to set the background color of a control which has no texture applied to it. This simply fills the control with a solid color, such as the titlebar of the texture viewer to the right. If you are familiar with the 0 to 255 scale for RGB, rgba simply translates that into a float of range 0 to 1, with alpha (color.a) equating to completely transparent at 0, completely opaque at 1.  
Line 133: Line 92:
 
*An rgba of 1,1,1,1 will result in the texture's appearance being unchanged from the original.  
 
*An rgba of 1,1,1,1 will result in the texture's appearance being unchanged from the original.  
 
*As you might guess from that, the default rgba for any given state presentation is 1,1,1,1.
 
*As you might guess from that, the default rgba for any given state presentation is 1,1,1,1.
 +
 +
[[Image:StatePresentation ColorPicker.png|Color Picker]]
 +
 +
<br>
 +
 +
=== Behavior ===
 +
 +
The [[GUI Controls#Behavior|Behavior]] properties determine how the control processes [[GUI_Events|GUI Events]], whether it appears on the screen, the [[GUI_Animations|GUI Animations]] the control uses and if the control is selected. If <code>IgnoreMouseEvents</code> is '''false''' then the control will process mouse input events. The value of <code>IgnoreMouseEvents</code> does not affect the control's parent or children.
 +
 +
[[Image:GUIProperties_Behavior.png|GUIProperties_Behavior.png]]
  
 
<br>
 
<br>
  
−
== Save Changes  ==
+
=== Data ===
  
−
*To save your changes, press the XML button on the toolbar to create the [[GUIXML]] code. The language will appear in the console window, along with a message that it has been copied to the clipboard. This is purely informational, however, as your GUIXML will have been automatically written to an .xml file in the repository.  
+
The [[GUI Controls#Data|Data]] of a GUI Control contains it's name, what prototype it's created from and what [[GUIXML]] file it's data is stored in. The control's '''name''' is used to uniquely identify it among all others in it's control hierarchy. If the [[GUI_functions#Find_GUI_Control_By_Name|FindGUIControlByName]] is used to find the control then the control's name must be unique among all other children control's of the <code>GUInode</code> parameter.
−
*Exit the GUI Editor by clicking on the button in the GUI Editor Toolbar that says "Close Editor".
+
 
 +
[[Image:GUIProperties_Data.png|GUIProperties_Data.png]]
 +
 
 +
<br>
 +
 
 +
=== Layout ===
 +
 
 +
[[GUI Controls#Layout|Layout]]
 +
 
 +
[[Image:GUIProperties_Layout.png|GUIProperties_Layout.png]]
 +
 
 +
<br>
 +
 
 +
=== Misc ===
 +
 
 +
[[GUI Controls#Misc|Misc]]
 +
 
 +
[[Image:GUIProperties_Misc.png|GUIProperties_Misc.png]]
 +
 
 +
<br>
 +
 
 +
=== Save Changes  ===
 +
 
 +
*To save your changes, press the XML button on the [[GUI Editor Toolbar|GUI Editor Toolbar]] to create the [[GUIXML]] code. The language will appear in the console window, along with a message that it has been copied to the clipboard. This is purely informational, however, as your GUIXML will have been automatically written to an .xml file in the repository.  
 +
*Exit the GUI Editor by clicking on the button in the [[GUI Editor Toolbar|GUI Editor Toolbar]] that says "Close Editor".
 +
 
 +
[[Image:GUIEditorToolbar.png|GUIEditorToolbar.png]]
 +
 
 +
<br>
 +
 
 +
== Create a New Prototype  ==
 +
 
 +
*In your [[Organizer Panel]] is a tab marked GUIXML. If you do not have the Organizer visible, select it from the [[Panels menu]].
 +
*Click the '''Create New''' link at the bottom of the GUIXML panel. This should open a window. It will have four inputs on it:
 +
**'''Prototype Name'''
 +
***This is the name of your window as it appears in the GUIXML tab. This namespace is shared amongst all GUI Control prototypes, so should be reasonably unique.
 +
**'''Description'''
 +
***This is a textual description of the purpose of the control, such as "Hero's Journey inventory window".
 +
**'''Inherit From'''
 +
***This is where you choose what base control/window to use to create your control.
 +
***It is advised that you create one base window control, and inherit from it to create more specific types such as an inventory window.
 +
**'''Class'''
 +
***Similar to inheritance, it is advisable to create one base window class, and create new classes to inherit from that as necessary. For more information on creating a class, see the [[Dom editor|Dom Editor]]. You should ensure that any classes you create for GUI Controls use the '''guicontrol''' archetype, as opposed to '''data'''.
 +
*Click the "Okay" button in the Window. The window will now be placed on the screen in its editable state.
 +
**Whenever possible, try to coordinate with coworkers so that you are not creating a new prototype simultaneously, as only one client at a time can currently write to the XML .lst files.
 +
*Note that the Properties Panel is now populated with the control's properties.
 +
*If you have inherited from an existing prototype such as "_window", you might click on the "+" next to the name of your new window in the directory tree at the top section of the Properties Panel. Note that it has several child controls, some of which may have their own children. As you click on the name of each one, the Properties Panel reflects the [[GUIXML]] properties for it, and a different section of the created window is highlighted, to show which part you are dealing with.
 +
**Only some properties may be changed on inherited children. For example, you can never change the '''name''' of an inherited control, nor can you change their order in their parent's children list. However, you can change many other useful properties, such as their layout (size, position, texture, color, et al) and script.
 +
*Clicking on the name of the control that you created results in the entire control being highlighted in the viewport.
 +
*Note that the selected control can be moved and resized, by dragging it around the screen.
 +
*You can add new children to whatever control you have selected (caveat: GUILabel controls can not display children) by double-clicking the name of the desired child in the Organizer panel.
 +
**Controls are added to whichever control is currently selected in the directory tree.
 +
**Any children associated with the new control's prototype are added as well.
 +
**The newly added control will be automatically selected when added, so if you are adding multiple controls to the same parent, be sure to reselect it each time (this is easily done by right-clicking in the GUI Editor area).
  
 
<br>  
 
<br>  
  
−
== See also ==
+
== See also ==
  
 
*[[GUIXML]]  
 
*[[GUIXML]]  

Revision as of 22:18, 4 November 2011

Contents

Overview

The GUIEditor allows for the creation of GUI Control Prototypes, in a WYSIWYG visual format. After a prototype has been created, a script can be written which creates nodes based on the prototype.

GUI Editor Properties


Starting the Editor

In older versions of HeroEngine, the GUI Editor needed to be started from the GUI Editor Toolbar.

In current versions, the GUI Editor is accessed by:


Using the Editor

The GUI Editor is used to modify the default value of a GUI Control's fields. The value of these fields are stored in a client-side prototype which is generated from GUIXML files. These fields are edited in the Properties Panel. When a prototype is opened for editing the Properties Panel will automatically open.

When editing a GUI Control prototype the layout of the Properties Panel is similar to how it looks if a Model was selected except the listed properties are different and there is a GUI Control Hierarchy Tree View at the top of the panel. The properties can be displayed in two ways, Categorized and Alphabetical. The Categorized view will split the properties into the following collapsible sections: Appearance, Behavior, Data, Layout, Misc and Presentation States. The Alphabetical view will list all of the properties in alphabetical order.


Appearance

The Appearance section of properties controls how the GUI Control's texture is displayed to all of the state presentation properties as well as the texture property, which is the Fully Qualified Name (FQN) of the texture file in the Repository.

GUIProperties_Appearance.png

GUI Textures

Art for GUI Controls must be stored in the Repository in the form of a DirectDraw Surface (.DDS) or .PNG file. To assign a texture to be used by a GUI Control you can use the Texture Viewer accessible from a state presentation field or the texture field.


Presentation States

A GUI control's State Presentation determines its appearance in various predefined states. There are five state presentations available to work with:

State presentations are complex fields with three subfields: size, position, and color. You will typically only be concerned with either size and position, or color, but will sometimes want to use all three.

Note that GUILabel class controls are treated differently by their state presentations. Changing the color of a GUILabel's state presentation will actually affect the text of the label, not provide a background color. Adding a texture to a GUILabel-based control will do nothing of interest.

Default state presentation properties


Texture Mapping in a state presentation

The size and position fields of a state presentation refer to the image specified by the control's texture field. If a control has no texture field declared, size and position will do nothing. Used in conjunction, these two fields determine the placement and size of a rectangular slice of the image, to be applied to the control. While state presentations may (and frequently will) use different areas of a .dds file to determine a control's appearance, they must all use the same texture file. You cannot have your hover states in one .dds file, and your disabled states in another. The texture viewer shown to the right can be pulled up by clicking in the texture field in the GUI Editor, or on any of the state presentation fields or subfields, with the exception of color.

In both cases, positive-x points toward the right edge of the image, while positive-y points towards the bottom. However, if either of the size xy fields are given negative values, the image will appear reversed along that axis, making it possible to reuse a single piece of a texture up to four different ways.

Note that one approach taken by some art departments is to create their GUI art at double the intended size, to allow for less pixelization when a control is scaled. In a situation such as this, the state presentation dimensions would still follow the same procedure as with a normal-sized texture, as the size field of the control still dictates its displayed appearance. For example, an icon whose art is created at 128x128 pixels may still be displayed as a 64x64 icon, simply by setting its state presentation size to 128x128, and its actual size to 64x64.

Texture Mapping in a state presentation


Color in a state presentation

Color, a complex field of type rgba, is most often used to set the background color of a control which has no texture applied to it. This simply fills the control with a solid color, such as the titlebar of the texture viewer to the right. If you are familiar with the 0 to 255 scale for RGB, rgba simply translates that into a float of range 0 to 1, with alpha (color.a) equating to completely transparent at 0, completely opaque at 1.

If a given state presentation has all three fields set, the texture's colors will be multiplied on a per-pixel basis by the RGBA you specify via the color field, essentially adding a tint to the texture. Texture multiplication is beyond the scope of this document, but here are a few simple guides:

Color Picker


Behavior

The Behavior properties determine how the control processes GUI Events, whether it appears on the screen, the GUI Animations the control uses and if the control is selected. If IgnoreMouseEvents is false then the control will process mouse input events. The value of IgnoreMouseEvents does not affect the control's parent or children.

GUIProperties_Behavior.png


Data

The Data of a GUI Control contains it's name, what prototype it's created from and what GUIXML file it's data is stored in. The control's name is used to uniquely identify it among all others in it's control hierarchy. If the FindGUIControlByName is used to find the control then the control's name must be unique among all other children control's of the GUInode parameter.

GUIProperties_Data.png


Layout

Layout

GUIProperties_Layout.png


Misc

Misc

GUIProperties_Misc.png


Save Changes

GUIEditorToolbar.png


Create a New Prototype


See also

Retrieved from "http://hewiki.heroengine.com/wiki/GUI_Editor"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox