Geep: Add category tag

2022-11-04T17:44:56Z

Add category tag

← Older revision		Revision as of 17:44, 4 November 2022
Line 175:		Line 175:
	===A ListDef that Didn't Make the Cut===		===A ListDef that Didn't Make the Cut===
	There was an initial attempt, In mainmenu_success.gui, to employ a listDef to show a list of statistics. This was replaced by a column of stacked windowDefs instead, because (reports greebo): "listDefs don't get updated in the GUI unless you call gui->StateChanged(), which in turn breaks the main menu. Hence: text fields instead of listDefs."		There was an initial attempt, In mainmenu_success.gui, to employ a listDef to show a list of statistics. This was replaced by a column of stacked windowDefs instead, because (reports greebo): "listDefs don't get updated in the GUI unless you call gui->StateChanged(), which in turn breaks the main menu. Hence: text fields instead of listDefs."

			{{GUI}}

Geep: /* Properties Specific to ListDefs */

2022-10-14T16:04:38Z

Properties Specific to ListDefs

← Older revision		Revision as of 16:04, 14 October 2022
Line 39:		Line 39:

	==Properties Specific to ListDefs==		==Properties Specific to ListDefs==
	® = A property known as a "register", that can be altered at runtime by binding it to a GUI:: parameter, or in a "set" or "transition" script command. Other properties cannot be so altered.		® = A property known as a "register", that can be altered at runtime by binding it to a GUI:: parameter, or in a "set" or "transition" script command. Other properties cannot be so altered, nor appear within event handlers.
	===Data Source===		===Data Source===
	====Listname "''name''"====		====Listname "''name''"====

Geep at 21:47, 16 August 2022

2022-08-16T21:47:13Z

← Older revision		Revision as of 21:47, 16 August 2022
Line 1:		Line 1:
	~~Title: GUI Scripting: ListDef~~
	''This page is part of a series. See [[GUI Scripting Language]] for overview.''		''This page is part of a series. See [[GUI Scripting Language]] for overview.''
	==Introduction==		==Introduction==

Geep: Add Internationalization? Sorry

2022-08-16T21:45:28Z

Add Internationalization? Sorry

← Older revision		Revision as of 21:45, 16 August 2022
Line 170:		Line 170:

	Internally, the actual data representing each table row is in a tab-separated string, placed into string array "listItems". This is pre-populated before rendering. There's also an array of integers, currentSel, that contains the 0-based indices of rows currently selected. This information is also stored in state interger variables named listName_sel_number, with a count in listname_sel_numsel. If the count is zero, listname_sel_0 is -1.		Internally, the actual data representing each table row is in a tab-separated string, placed into string array "listItems". This is pre-populated before rendering. There's also an array of integers, currentSel, that contains the 0-based indices of rows currently selected. This information is also stored in state interger variables named listName_sel_number, with a count in listname_sel_numsel. If the count is zero, listname_sel_0 is -1.

			===Internationalization? Sorry===
			There appears to be no inherent i18n support in listDef. That is, in the prepopulated string array "listItems", with tab-separated substrings, the prefix "#str_" has no special meaning or handling. So if you want to localize the list contents, this must be done by detecting the TDM language in effect, then prepopulating listItems with the language-specific content. This evidently is not done currently, e.g., in DownloadMenu.cpp or MissionManager.cpp or server-side, so the FM titles displayed are not translated.

	===A ListDef that Didn't Make the Cut===		===A ListDef that Didn't Make the Cut===
	There was an initial attempt, In mainmenu_success.gui, to employ a listDef to show a list of statistics. This was replaced by a column of stacked windowDefs instead, because (reports greebo): "listDefs don't get updated in the GUI unless you call gui->StateChanged(), which in turn breaks the main menu. Hence: text fields instead of listDefs."		There was an initial attempt, In mainmenu_success.gui, to employ a listDef to show a list of statistics. This was replaced by a column of stacked windowDefs instead, because (reports greebo): "listDefs don't get updated in the GUI unless you call gui->StateChanged(), which in turn breaks the main menu. Hence: text fields instead of listDefs."

Geep: create this article

2022-08-13T22:01:08Z

create this article

New page

Title: GUI Scripting: ListDef
''This page is part of a series. See [[GUI Scripting Language]] for overview.''
==Introduction==
One of the more complex controls, a listDef displays a vertical list of items in rows, from which the user selects by clicking. A row can be composed of multiple data columns, that the listDef defines using "tab stops". A column of this table will have either text or icons in it.

The listDef GUI does not itself populate a list, but relies on associated C++ code to do so, typically with a dynamic list.

===ListDefs in TDM's Main Menu System===
====Load/Save====
After hitting "Load/Save", a page with a list of saved missions appears. Each row has 3 text columns: a short name for the save, and the date and time when saved. This employs "listDef LGSaveGameList" in tdm_gui01.pk4\guis\mainmenu_loadsave.gui . When a game is in-process and this menu is invoked, the user is able to select a row. At that point, "Load", "Save", and "Delete" buttons become enabled, along with a field to rename a saved game, e.g., from an autogenerated name like "QuickSave_0" to something more meaningful.

====New Mission====
After hitting "New Mission", the "Available Missions" list appears, showing FMs installed locally. Games played to completion are marked with a green checkmark icon in the second column. This employs "listDef choosemod_list" in mainmenu_newgame.gui . See "New Mission Example" further below.

====Download Missions====
From the menu page with "Available Missions" just discussed, the "Download Missions" button brings up two pages. The lefthand one, "Online Mission Archive", has a list "Downloadable Missions" using a single-column listDef populated by the server. The righthand one, "Download Status", has a "Selected for Download" list, populated by the user. These two pages are defined in mainmenu_download.gui, that has "listDef available_list" and "listDef selected_list".

Beneath the lefthand list are two buttons, "Select All >>" and "Select for download >>". These copy entries from the lefthand list to the righthand. Note that the lefthand list is not multiple-selection. Instead, the user populates the righthand list one selection at a time (or all - with a dedicated button). Clicking an FM in the righthand list deletes it, undoing its selection for download. "Selected for Download" has 2 text columns. Once downloading begins, the second column shows the percentage downloaded so far.

===Keystrokes and Mouse Actions===
''This is somewhat simplified. See "Additional Notes" below for more.''

====Adjusting the Set of Visible Rows within the Scrollable Area====
* LMB drag vertical scrollbar thumb: adjust rows.
* LMB click in scrollbar area: thumb jumps to location; adjust rows.
* Up arrow or mouse wheel up or RMB above scrollbar thumb: up 1 row.
* Down arrow or mouse wheel down or RMB below scrollbar thumb: down 1 row.
* Page Up: up by the number of visible rows.
* Page Down: down by the number of visible rows.

====Selection====
* LMB on a data row: if clear, select it, and clear any other row.
* Alphanumeric string: Find and select topmost row with prefix match in first text column. Adjust set of visible rows as needed. Entry string (which is hidden) can be extended to change selection. Hidden string can be cleared by manually selecting a row.
* Any change of row selection: onAction handler.
* With a row selected, Enter or Keypad Enter: onEnter handler.
* Row LMB double-click: select (if not already) then onEnter handler.

==Properties Shared with All GuiDef Types==
A listDef will employ [[GUI Scripting: Properties in Common | Properties in Common]] to size its rectangle and set the attributes of its text, including mouse hover. In practice, [[GUI Scripting: User Variables | User Variables]] don't seem to be much used. [[GUI Scripting: Event Handlers | Event Handlers]] for onAction, onEnter, onMouseEnter, and onMouseExit are important.

==Properties Specific to ListDefs==
® = A property known as a "register", that can be altered at runtime by binding it to a GUI:: parameter, or in a "set" or "transition" script command. Other properties cannot be so altered.
===Data Source===
====Listname "''name''"====
Specifies the C++ name of the list whose contents the listDef will display. This name may or may not be different from "listDef ''name''". The listname string is referenced by the code to populate the list and to use as a prefix when naming internal state variables.
listname "downloadSelectedList"

===For Multi-Column Lists===
These Properties take strings with comma-separated values, where each value is for a sequential "tab stop", that is, table column.
====Tabaligns "''comma_separated_values''"====
Has "textalign" values for each column: 0 = Left, 1 = Center, 2 = Right.
tabAligns "0, 1" // From manmenu_newgame.gui, indicating "Left, Center"
====Tabstops "''comma_separated_values''"====
Has the x-axis offset of each column.
tabstops "0, 228"
===For Icons in Multi-Column Lists===
These were not mentioned in Ref 1 of [[GUI Scripting: References & Resources]]; are they TDM specific?
====TabTypes "''comma_separated_values''"====
Content type for each column. 0 = text, 1 = icon. If not given, all columns are 0 (Text).
tabTypes "0, 1" // Text, Icon
====Tabvaligns "''comma_separated_values''"====
For icons, not text, has vertical alignment values for each column: 0=Top, 1=Center, 2=Bottom. Default alignments are Top.
Tabvaligns "0, 1"
====TabIconSizes "''comma_separated_value_pairs''"====
This should have twice as many values as the number of columns. Text columns should have "0,0".
tabIconSizes "0,0, 14,14" // TabStop 1 size is 15w x 15h
====TabIconVOffset "''comma_separated_values''"====
tabIconVOffset "0, 1"
====Mtr_''suffix'' "''path_to_mtr''"====
Specifies the material (e.g., image) used for the icon. Property name must start with prefix "mtr_", then be unique. There may be any number of these in a GUI. For columns of tabtype "icon":
* an "mtr..." name appearing in the data will be interpreted as an icon's material definition, not a literal string.
* An empty string will indicate a table cell with no icon.
mtr_complete "guis/assets/mainmenu/buttons_start/icon_completed" // green checkmark

===Addition ListDef Properties – Not Used in TDM Core===
====Horizontal ''bool''====
If 1 (true), then the table uses a horizontal scrollbar instead of a vertical one. Untested, says Ref 1 of [[GUI Scripting: References & Resources]]. Unclear what behavior was intended. Default: 0 (false).
horizontal 1
====Multiplesel ''bool''====
Indicates if the user can select more than one row simultaneously. (Requires code support, says Ref 1 of [[GUI Scripting: References & Resources]].) Default: 0 (false).
multilesel 1

==New Game Example==
This fragment from mainmenu_newgame.gui is a good example of the Properties needed for a 2-column table with text and icons. As for event handlers, when a mission is selected for possible install, a lefthand windowDef, "modToInstallVisible", will appear to describe it. Invocation of that window is done by the onAction handler shown here (though details of the windowDef itself is not).
...
windowDef choosemod_parent
{
rect 330,164,320,245
visible 1
matcolor 1,1,1,1

listDef choosemod_list
{
rect 0,0,270,245
bordercolor 0.0, 0.0, 0.0, 0.2
forecolor 0, 0, 0, 1
hovercolor 1, 1, 1, 1
textscale 0.29
listname "missionList"
font "fonts/carleton"
tabstops "0, 228" // Mission Name, Mission Complete Icon
tabAligns "0, 1" // Left, Center
tabTypes "0, 1" // Text, Icon
tabIconSizes "0,0, 14,14" // TabStop 1 size 15,15
tabIconVOffset "0, 1"
tabvaligns "0, 1" // Only works for icon columns

mtr_complete "guis/assets/mainmenu/buttons_start/icon_completed"

onAction {
set "cmd" "onMissionSelected";
set "cmd" "play sound/meta/menu/mnu_select";
if ("gui:missionList_sel_0" >= 0)
{
set "modToInstallVisible" "1";
}
}
}
}
...

==Download Selected-List Example==
See the "Introduction" above for an overall description of the two download tables. Here, there's a glimpse from mainmenu_download.gui, concerning the righthand "Selected for download" table. The fragment shows a 2-column list defined by tab stops. The user creates a download batch, with the mission names in the left column, download progress (initially blank) in the right column. If a mission needs to be removed from the batch, a LMB click (and the onAction handler shown) does it. Actual download processing, including updating the right column text values, is handled elsewhere.
...
listDef selected_list
{
rect 0,0,240,185
bordercolor 0.0, 0.0, 0.0, 0.2
forecolor 0, 0, 0, 1
hovercolor 1, 1, 1, 1
textscale 0.257
listname "downloadSelectedList"
font "fonts/carleton"
tabstops "0, 185" // Mission Name, Download Progress
tabAligns "0, 0" // Left, Left
tabTypes "0, 0" // Text, Text

onAction {
set "cmd" "play sound/meta/menu/mnu_select;";
set "cmd" "onDeselectMissionForDownload";
}
}
...

==Additional Notes==
===Keystrokes and Mouse Actions===
====If Multiple Selection is Enabled====
If "multiplesel 1" is in effect for the listDef, then...
Ctrl+LMB on data row: If already selected, clear; if clear, select it too.

====Load/Save's Special Handling of Row Double-Click====
As indicated in the Introduction, a LMB double-click on a row will select that row (if not already selected) and call an onEnter handler. In the case of mainmenu_loadsave.gui, that handler will then do nothing when this is during a game, because both the Load and Save buttons are visible and it's not clear which is meant. If it's pre-game, though, only the Load button is present and so the double-clicks acts as if that was pushed.

====Scrollbar Related====
LMB or RMB clicks in the scroller are ignored in ListWindow.cpp, and handled instead in the scrollbar's idSliderWindow class. That is, scrollbars for listDefs and editDefs are implemented by the idSliderWindow class in SliderWindow.cpp (not to be confused with sliderDef.) Mouse actions on the scrollbar are handled there in its HandleEvent function, as follows.
As mentioned in the Introduction, while the LMB is dragging the thumb, capture the mouse coordinates to move the thumb. Otherwise...
* RMB clicked above thumb: visible rows up a row
* RMB clicked below thumb: visible rows down a row

The code has a treatment for these additional keys, but these '''DON'T WORK''', presumably because the keystrokes are not reaching this code:
* Right Arrow or Keypad Right Arrow: visible rows up a row
* Left Arrow or Keypad Left Arrow: visible rows down a row

Finally, a usability complaint. Because the implementation of the listDef's vertical scrollbar shows its thumb just as black dot, its behavior (when clicked or dragged) can seem mysterious. It would be better if the thumb was a more-conventional rectangle whose height reflected the percentage of the number of rows that the visible rows exposed.

===Layout and Data Implementation===
The operations of a listDef are supported by the idListGUILocal class in ListGUI.cpp and idListWindow in ListWindow.cpp. Incoming keystrokes and mouse actions are dealt with in ListWindow.cpp's idListWindow::HandleEvent(...).

Each GUI Parameter with comma-separated information about each column is first parsed, split, and stored into an associated internal array. The information in these arrays are then copied and repackaged together into a "tabInfo" array, representing the columns of any row, where each element describes all the attributes of the cell and its contents, including its border dimensions.

Internally, the actual data representing each table row is in a tab-separated string, placed into string array "listItems". This is pre-populated before rendering. There's also an array of integers, currentSel, that contains the 0-based indices of rows currently selected. This information is also stored in state interger variables named listName_sel_number, with a count in listname_sel_numsel. If the count is zero, listname_sel_0 is -1.

===A ListDef that Didn't Make the Cut===
There was an initial attempt, In mainmenu_success.gui, to employ a listDef to show a list of statistics. This was replaced by a column of stacked windowDefs instead, because (reports greebo): "listDefs don't get updated in the GUI unless you call gui->StateChanged(), which in turn breaks the main menu. Hence: text fields instead of listDefs."

GUI Scripting: ListDef - Revision history

Geep: Add category tag

Geep: /* Properties Specific to ListDefs */

Geep at 21:47, 16 August 2022

Geep: Add Internationalization? Sorry

Geep: create this article