Aller au contenu principal
Version: 20 R5 BETA

List Box

Les list box sont des objets actifs complexes permettant d’afficher et de saisir des données sous forme de tableaux. Ils peuvent être liés au contenu de la base de données, comme les sélections d'entités ("entity selections") et les sélections d'enregistrement, ou à tout contenu linguistique tel que les collections et les tableaux. Ils incluent des fonctionnalités avancées concernant la saisie de données, le tri des colonnes, la gestion des événements, l'apparence personnalisée, le déplacement des colonnes, etc.

Une list box contient une ou plusieurs colonnes dont le contenu est automatiquement synchronisé. Le nombre de colonnes est en principe illimité (il dépend des ressources de la machine).

Vue d’ensemble

Principes d'utilisation basiques

En exécution, les list box permettent d’afficher et de saisir des données sous forme de listes. To make a cell editable (if entry is allowed for the column), simply click twice on the value that it contains:

Les utilisateurs peuvent saisir et afficher du texte sur plusieurs lignes au sein d’une cellule de list box. To add a line break, press Ctrl+Carriage return on Windows or Option+Carriage return on macOS.

Les booléens et les images peuvent être affichés dans des cellules, ainsi que des dates, des heures ou des nombres. It is possible to sort column values by clicking on a header (standard sort). Toutes les colonnes sont automatiquement synchronisées.

It is also possible to resize each column, and the user can modify the order of columns and rows by moving them using the mouse, if this action is authorized. Note that list boxes can be used in hierarchical mode.

The user can select one or more rows using the standard shortcuts: Shift+click for an adjacent selection and Ctrl+click (Windows) or Command+click (macOS) for a non-adjacent selection.

Parties de list box

Une list box est composée de quatre parties distinctes :

  • l’objet list box dans sa globalité,
  • les colonnes,
  • les en-têtes des colonnes, et
  • les pieds des colonnes.

Chaque partie dispose de son propre nom d’objet et de propriétés spécifiques. Par exemple, le nombre de colonnes ou la couleur alternée de chaque ligne sont définies dans les propriétés de l’objet list box, la largeur de chaque colonne est définie dans les propriétés des colonnes et la police de l’en-tête est définie dans les propriétés des en-têtes.

Il est possible d'ajouter une méthode objet à l'objet list box et/ou à chaque colonne de la list box. Les méthodes objet sont appelées dans l'ordre suivant :

  1. Méthode objet de chaque colonne
  2. Méthode objet de la list box

The column object method gets events that occur in its header and footer.

Types de list box

Il existe différents types de list box avec leurs propres comportements et propriétés spécifiques. The list box type depends on its Data Source property:

  • Arrays: each column is bound to a 4D array. Array-based list boxes can be displayed as hierarchical list boxes.
  • Selection (Current selection or Named selection): each column is bound to an expression (e.g. a field) which is evaluated for every record of the selection.
  • Collection or Entity selection: each column is bound to an expression which is evaluated for every element of the collection or every entity of the entity selection.

Il n'est pas possible de combiner différents types de list box dans le même objet list box. La source de données est définie lors de la création de la list box. Il n'est alors plus possible de la modifier par programmation.

Gestion des list box

Vous pouvez configurer complètement un objet de type list box via ses propriétés, et vous pouvez également le gérer dynamiquement par programmation.

The 4D Language includes a dedicated "List Box" theme for list box commands, but commands from various other themes, such as "Object properties" commands or EDIT ITEM, Displayed line number commands can also be used. Refer to the List Box Commands Summary page of the 4D Language reference for more information.

Objets List box

List box de type tableau

Dans une list box de type tableau, chaque colonne est associée à un tableau 4D à une dimension ; tous les types de tableaux peuvent être utilisés, à l’exception des tableaux de pointeurs. Le nombre de lignes est basé sur le nombre d’éléments du tableau.

Par défaut, 4D affecte le nom “ColonneN” à chaque variable de colonne. You can change it, as well as other column properties, in the column properties. The display format for each column can also be defined using the OBJECT SET FORMAT command.

Array type list boxes can be displayed in hierarchical mode, with specific mechanisms.

Avec les list box de type tableau, les valeurs des colonnes (saisie et affichage) sont gérées à l’aide des commandes du langage 4D. You can also associate a choice list with a column in order to control data entry. The values of columns are managed using high-level List box commands (such as LISTBOX INSERT ROWS or LISTBOX DELETE ROWS) as well as array manipulation commands. Par exemple, pour initialiser le contenu d’une colonne, vous pouvez utiliser l’instruction suivante :

ARRAY TEXT(varCol;size)

Vous pouvez également utiliser une énumération :

LIST TO ARRAY("ListName";varCol)

Warning: When a list box contains several columns of different sizes, only the number of items of the smallest array (column) will be displayed. Il est donc conseillé de veiller à ce que chaque tableau ait le même nombre d’éléments que les autres. A noter également que si une colonne de la list box est “vide” (c'est le cas lorsque le tableau associé n'a pas été correctement déclaré ou dimensionné via le langage), la list box n'affiche aucun contenu.

List box de type sélection

In this type of list box, each column can be associated with a field (for example [Employees]LastName) or an expression. The expression can be based on one or more fields (for example, [Employees]FirstName+" "[Employees]LastName) or it may simply be a formula (for example String(Milliseconds)). L’expression peut également être une méthode projet, une variable ou un élément de tableau. You can use the LISTBOX SET COLUMN FORMULA and LISTBOX INSERT COLUMN FORMULA commands to modify columns programmatically.

The contents of each row is then evaluated according to a selection of records: the current selection of a table or a named selection.

Dans le cas d’une list box basée sur la sélection courante, toute modification effectuée côté base de données est automatiquement reportée dans la list box et inversement. La sélection courante est donc toujours identique aux deux emplacements.

List box collection ou entity selection

Dans ce type de list box, chaque colonne doit être associée à une expression. Le contenu de chaque ligne est ensuite évalué par élément de la collection ou par entité de l'entity selection.

Each element of the collection or each entity is available as an object that can be accessed through the This keyword. A column expression can be a property path, a project method, a variable, or any formula, accessing each entity or collection element object through This, for example This.<propertyPath> (or This.value in case of a collection of scalar values). You can use the LISTBOX SET COLUMN FORMULA and LISTBOX INSERT COLUMN FORMULA commands to modify columns programmatically.

Lorsque la source de données est une entity selection, les modifications apportées du côté de la list box sont automatiquement enregistrées dans la base de données. En revanche, les modifications apportées du côté de la base de données sont visibles dans la list box après le rechargement des entités modifiées.

Lorsque la source de données est une collection, toute modification apportée aux valeurs de la list box se reflète dans la collection. On the other hand, if modifications are done on the collection using for example the various functions of the Collection class, you will need to explicitely notify 4D by reassigning the collection variable to itself, so that the list box contents is refreshed. Par exemple :

myCol:=myCol.push("new value") //afficher new value dans la list box

Propriétés prises en charge

Les propriétés prises en charge dépendent du type de list box.

PropriétéList box tableauListe box sélectionList box collection ou entity selection
Alternate Background ColorXXX
Background ColorXXX
BoldXXX
Background Color ExpressionXX
Border Line StyleXXX
BottomXXX
ClassXXX
Collection or entity selectionXX
Column Auto-ResizingXXX
Current itemX
Current item positionX
Data SourceXXX
Detail Form NameX
Display HeadersXXX
Display FootersXXX
Double-click on rowX
DraggableXXX
DroppableXXX
FocusableXXX
FontXXX
Font ColorXXX
Font Color ExpressionXX
Font SizeXXX
Height (list box)XXX
Height (headers)XXX
Height (footers)XXX
Hide extra blank rowsXXX
Hide focus rectangleXXX
Hide selection highlightXXX
Hierarchical List BoxX
Highlight SetX
Horizontal AlignmentXXX
Horizontal Line ColorXXX
Horizontal PaddingXXX
Horizontal Scroll BarXXX
Horizontal SizingXXX
ItalicXXX
LeftXXX
Master TableX
Meta info expressionX
MethodXXX
Movable RowsX
Named SelectionX
Number of ColumnsXXX
Number of Locked ColumnsXXX
Number of Static ColumnsXXX
Object NameXXX
RightXXX
Row Background Color ArrayX
Row Control ArrayX
Row Font Color ArrayX
Row HeightX
Row Height ArrayX
Row Style ArrayX
Selected ItemsX
Selection ModeXXX
Single-Click EditXXX
SortableXXX
Standard actionX
Style ExpressionXX
TopXXX
TransparentXXX
TypeXXX
UnderlineXXX
Variable or ExpressionXX
Vertical AlignmentXXX
Vertical Line ColorXXX
Vertical PaddingXXX
Vertical Scroll BarXXX
Vertical SizingXXX
VisibilityXXX
WidthXXX

Les colonnes, en-têtes et pieds de list box prennent en charge des propriétés spécifiques.

Événements formulaire pris en charge

Evénement formulaireAdditional Properties Returned (see Form event for main properties)Commentaires
On After Edit
  • column
  • columnName
  • row
  • On After Keystroke
  • column
  • columnName
  • row
  • On After Sort
  • column
  • columnName
  • headerName
  • Les formules composées ne peuvent pas être triées.
    (ex : This.firstName + This.lastName)
    On Alternative Click
  • column
  • columnName
  • row
  • Listbox tableau uniquement
    On Before Data Entry
  • column
  • columnName
  • row
  • On Before Keystroke
  • column
  • columnName
  • row
  • On Begin Drag Over
  • column
  • columnName
  • row
  • On Clicked
  • column
  • columnName
  • row
  • On Close Detail
  • row
  • Current Selection & Named Selection list boxes only
    On Collapse
  • column
  • columnName
  • row
  • List box hiérarchiques uniquement
    On Column Moved
  • columnName
  • newPosition
  • oldPosition
  • On Column Resize
  • column
  • columnName
  • newSize
  • oldSize
  • On Data Change
  • column
  • columnName
  • row
  • On Delete Action
  • row
  • On Display Detail
  • isRowSelected
  • row
  • On Double Clicked
  • column
  • columnName
  • row
  • On Drag Over
  • area
  • areaName
  • column
  • columnName
  • row
  • On Drop
  • column
  • columnName
  • row
  • On Expand
  • column
  • columnName
  • row
  • List box hiérarchiques uniquement
    On Footer Click
  • column
  • columnName
  • footerName
  • Arrays, Current Selection & Named Selection list boxes only
    On Getting Focus
  • column
  • columnName
  • row
  • Propriétés supplémentaires retournées uniquement lors de la modification d'une cellule
    On Header Click
  • column
  • columnName
  • headerName
  • On Load
    On Losing Focus
  • column
  • columnName
  • row
  • Propriétés supplémentaires retournées uniquement lorsque la modification d'une cellule est achevée
    On Mouse Enter
  • area
  • areaName
  • column
  • columnName
  • row
  • On Mouse Leave
    On Mouse Move
  • area
  • areaName
  • column
  • columnName
  • row
  • On Open Detail
  • row
  • Current Selection & Named Selection list boxes only
    On Row Moved
  • newPosition
  • oldPosition
  • Listbox tableau uniquement
    On Selection Change
    On Scroll
  • horizontalScroll
  • verticalScroll
  • On Unload

    Propriétés supplémentaires

    Les événements formulaire sur les list box ou colonnes de list box peuvent retourner les propriétés supplémentaires suivantes :

    PropriétéTypeDescription
    areatextZone de l'objet List box ("header", "footer", "cell")
    areaNametextNom de la zone
    columnentier longNuméro de colonne
    columnNametextNom de la colonne
    footerNametextNom du pied
    headerNametextNom de l'en-tête
    horizontalScrollentier longPositif si le défilement est vers la droite, négatif s'il est vers la gauche
    isRowSelectedbooleanVrai si la ligne est sélectionnée, sinon Faux
    newPositionentier longNouvelle position de la colonne ou de la ligne
    newSizeentier longNouvelle taille (en pixels) de la colonne ou de la ligne
    oldPositionentier longPosition précédente de la colonne ou de la ligne
    oldSizeentier longTaille précédente (en pixels) de la colonne ou de la ligne
    rowentier longNuméro de ligne
    verticalScrollentier longPositif si le défilement est vers le bas, négatif s'il est vers le haut

    Si un événement se produit sur une "fake" colonne ou ligne qui n'existe pas, une chaîne vide est généralement renvoyée.

    Colonnes de list box

    Une list box est composée d'un ou plusieurs objets colonnes qui ont des propriétés spécifiques. Vous pouvez sélectionner une colonne de list box dans l’éditeur de formulaires en cliquant dessus lorsque l’objet List box est sélectionné :

    You can set standard properties (text, background color, etc.) for each column of the list box; these properties take priority over those of the list box object properties.

    You can define the Expression type for array list box columns (String, Text, Number, Date, Time, Picture, Boolean, or Object).

    Propriétés spécifiques des colonnes

    Alpha Format - Alternate Background Color - Automatic Row Height - Background Color - Background Color Expression - Bold - Choice List - Class - Data Type (selection and collection list box column) - Date Format - Default Values - Display Type - Enterable - Entry Filter - Excluded List - Expression - Expression Type (array list box column) - Font - Font Color - Horizontal Alignment - Horizontal Padding - Italic - Invisible - Maximum Width - Method - Minimum Width - Multi-style - Number Format - Object Name - Picture Format - Resizable - Required List - Row Background Color Array - Row Font Color Array - Row Style Array - Save as - Style Expression - Text when False/Text when True - Time Format - Truncate with ellipsis - Underline - Variable or Expression - Vertical Alignment - Vertical Padding - Width - Wordwrap

    Événements formulaire pris en charge

    Evénement formulaireAdditional Properties Returned (see Form event for main properties)Commentaires
    On After Edit
  • column
  • columnName
  • row
  • On After Keystroke
  • column
  • columnName
  • row
  • On After Sort
  • column
  • columnName
  • headerName
  • Les formules composées ne peuvent pas être triées.
    (ex : This.firstName + This.lastName)
    On Alternative Click
  • column
  • columnName
  • row
  • Listbox tableau uniquement
    On Before Data Entry
  • column
  • columnName
  • row
  • On Before Keystroke
  • column
  • columnName
  • row
  • On Begin Drag Over
  • column
  • columnName
  • row
  • On Clicked
  • column
  • columnName
  • row
  • On Column Moved
  • columnName
  • newPosition
  • oldPosition
  • On Column Resize
  • column
  • columnName
  • newSize
  • oldSize
  • On Data Change
  • column
  • columnName
  • row
  • On Double Clicked
  • column
  • columnName
  • row
  • On Drag Over
  • area
  • areaName
  • column
  • columnName
  • row
  • On Drop
  • column
  • columnName
  • row
  • On Footer Click
  • column
  • columnName
  • footerName
  • Arrays, Current Selection & Named Selection list boxes only
    On Getting Focus
  • column
  • columnName
  • row
  • Propriétés supplémentaires retournées uniquement lors de la modification d'une cellule
    On Header Click
  • column
  • columnName
  • headerName
  • On Load
    On Losing Focus
  • column
  • columnName
  • row
  • Propriétés supplémentaires retournées uniquement lorsque la modification d'une cellule est achevée
    On Row Moved
  • newPosition
  • oldPosition
  • Listbox tableau uniquement
    On Scroll
  • horizontalScroll
  • verticalScroll
  • On Unload

    En-têtes de list box

    To be able to access the header properties of a list box, you must enable the Display Headers option of the list box.

    Lorsque les en-têtes sont affichés, vous pouvez sélectionner un en-tête dans l'éditeur de formulaires en cliquant dessus lorsque l'objet List box est sélectionné :

    Vous pouvez définir, pour chaque en-tête de colonne de List box, des propriétés standard de texte : dans ce cas, ces propriétés sont prioritaires par rapport à celles de la colonne ou de la list box.

    Vous pouvez également accéder à des propriétés spécifiques aux en-têtes. Specifically, an icon can be displayed in the header next to or in place of the column title, for example when performing customized sorts.

    At runtime, events that occur in a header are generated in the list box column object method.

    When the OBJECT SET VISIBLE command is used with a header, it is applied to all headers, regardless of the individual element set by the command. For example, OBJECT SET VISIBLE(*;"header3";False) will hide all headers in the list box object to which header3 belongs and not simply this header.

    Propriétés spécifiques des en-têtes

    Bold - Class - Font - Font Color - Help Tip - Horizontal Alignment - Horizontal Padding - Icon Location - Italic - Object Name - Pathname - Title - Underline - Variable or Expression - Vertical Alignment - Vertical Padding - Width

    Pieds de list box

    To be able to access footer properties for a list box, you must enable the Display Footers option.

    Les List box peuvent contenir des zones de "pied de page" non saisissables, affichant des informations supplémentaires. Dans les données présentées sous forme de tableaux, les pieds sont généralement utilisés pour afficher des calculs, tels que des sommes ou des moyennes.

    Lorsque les pieds sont affichés, vous pouvez sélectionner un pied de list box dans l’éditeur de formulaires en cliquant dessus lorsque l’objet List box est sélectionné :

    Vous pouvez définir, pour chaque pied de colonne de List box, des propriétés standard de texte : dans ce cas, ces propriétés sont prioritaires par rapport à celles de la colonne ou de la list box. Vous pouvez également accéder à des propriétés spécifiques pour les pieds de page. In particular, you can insert a custom or automatic calculation.

    At runtime, events that occur in a footer are generated in the list box column object method.

    When the OBJECT SET VISIBLE command is used with a footer, it is applied to all footers, regardless of the individual element set by the command. For example, OBJECT SET VISIBLE(*;"footer3";False) will hide all footers in the list box object to which footer3 belongs and not simply this footer.

    Propriétés spécifiques des pieds de page

    Alpha Format - Background Color - Bold - Class - Date Format - Expression Type - Font - Font Color - Help Tip - Horizontal Alignment - Horizontal Padding - Italic - Number Format - Object Name - Picture Format - Time Format - Truncate with ellipsis - Underline - Variable Calculation - Variable or Expression - Vertical Alignment - Vertical Padding - Width - Wordwrap

    Gestion de la saisie

    Pour qu’une cellule de list box soit saisissable, il est nécessaire que les conditions suivantes soient réunies :

    • The cell’s column must have been set as Enterable (otherwise, the cells of the column can never be enterable).
    • In the On Before Data Entry event, $0 does not return -1. When the cursor arrives in the cell, the On Before Data Entry event is generated in the column method. Si, dans le contexte de cet événement, $0 est défini sur -1, la cellule est considérée comme non saisissable. If the event was generated after Tab or Shift+Tab was pressed, the focus goes to either the next cell or the previous one, respectively. Si la valeur de $0 n'est pas -1 (par défaut $0 est 0), la cellule est saisissable et passe en mode d'édition.

    Imaginons par exemple une list box contenant deux tableaux, de type date et texte. Le tableau date n’est pas saisissable mais le tableau texte est saisissable si la date n’est pas déjà passée.

    Here is the method of the arrText column:

     Case of
    :(FORM event.code=On Before Data Entry) // a cell gets the focus
    LISTBOX GET CELL POSITION(*;"lb";$col;$row)
    // identification of cell
    If(arrDate{$row}<Current date) // if date is earlier than today
    $0:=-1 // cell is NOT enterable
    Else
    // otherwise, cell is enterable
    End if
    End case

    The On Before Data Entry event is returned before On Getting Focus.

    Afin de préserver la cohérence des données pour les list box de type de sélection et entity sélection, tout enregistrement/entité modifié(e) est automatiquement sauvegardé(e) dès que la cellule est validée, c'est-à-dire :

    • lorsque la cellule est désactivée (l'utilisateur appuie sur la touche tabulation, clique, etc.),
    • lorsque la list box n'a plus le focus,
    • lorsque le formulaire perd le focus.

    La séquence typique d'événements générés pendant la saisie ou la modification des données est la suivante :

    ActionType(s) de ListboxSéquence d'événements
    A cell switches to edit mode (user action or a call to the EDIT ITEM command)TousOn Before Data Entry
    TousOn Getting Focus
    Sa valeur est modifiéeTousOn Before Keystroke
    TousOn After Keystroke
    TousOn After Edit
    Un utilisateur valide et quitte la celluleList box de type sélectionSauvegarde
    List box de type sélection d'enregistrementsTrigger On saving an existing record (si défini)
    List box de type sélectionOn Data Change(*)
    List box de type entity selectionL'entité est sauvegardée avec l'option automerge, verrouillage optimiste (voir entity.save()). En cas de sauvegarde réussie, l'entité est rafraîchie avec la dernière mise à jour effectuée. Si la sauvegarde échoue, une erreur est affichée.
    TousOn Losing Focus

    (*) Avec les list box de type entity selection, dans l'événement "On Data Change" :

    • the Current item object contains the value before modification.
    • the This object contains the modified value.

    La saisie de données dans les list box de type collection/entity selection présente une limitation lorsque l'expression est évaluée comme nulle. Dans ce cas, il n'est pas possible de modifier ou de supprimer la valeur nulle dans la cellule.

    Gestion des sélections

    La gestion des sélections s'effectue différemment selon que la list box de type tableau, sélection d'enregistrements, ou collection/entity selection :

    • Selection list box: Selections are managed by a set, which you can modify if necessary, called $ListboxSetX by default (where X starts at 0 and is incremented based on the number of list boxes in the form). This set is defined in the properties of the list box. Il est maintenu automatiquement par 4D : si l'utilisateur sélectionne une ou plusieurs ligne(s) dans la list box, l'ensemble est immédiatement mis à jour. A l'inverse, il est possible d'utiliser les commandes du thème "Ensembles" afin de modifier par programmation la sélection dans la list box.

    • Collection/Entity selection list box: Selections are managed through dedicated list box properties:

    • Array list box: The LISTBOX SELECT ROW command can be used to select one or more rows of the list box by programming. The variable linked to the List box object is used to get, set or store selections of object rows. Cette variable correspond à un tableau de booléens automatiquement créé et maintenu par 4D. La taille de ce tableau est déterminée par celle de la list box : il contient le même nombre d’éléments que le plus petit tableau associé aux colonnes. Each element of this array contains True if the corresponding line is selected and False otherwise. 4D met à jour le contenu de ce tableau en fonction des actions utilisateur. A l’inverse, vous pouvez modifier la valeur des éléments de ce tableau afin de modifier la sélection dans la list box. En revanche, vous ne pouvez ni insérer ni supprimer de ligne dans ce tableau ; il n’est pas possible non plus de le retyper. The Count in array command can be used to find out the number of selected lines. Par exemple, cette méthode permet d’inverser la sélection de la première ligne de la list box (type tableau) :

     ARRAY BOOLEAN(tBListBox;10)
    //tBListBox is the name of the list box variable in the form
    If(tBListBox{1}=True)
    tBListBox{1}:=False
    Else
    tBListBox{1}:=True
    End if

    The OBJECT SET SCROLL POSITION command scrolls the list box rows so that the first selected row or a specified row is displayed.

    Personnaliser la représentation des sélections de lignes

    When the Hide selection highlight option is selected, you need to make list box selections visible using available interface options. Comme les sélections elles-mêmes sont gérées par 4D, cela signifie que :

    • Pour les list box de type tableau, vous devez parcourir le tableau booléen associé à la list box afin de déterminer quelles lignes sont sélectionnées.
    • For selection type list boxes, you have to check whether the current record (row) belongs to the set specified in the Highlight Set property of the list box.

    Vous pouvez alors définir par programmation des couleurs d'arrière-plan, des couleurs ou des styles de polices spécifiques permettant de visualiser l'apparence des lignes sélectionnées. Pour cela, vous pouvez utiliser des tableaux ou des expressions en fonction du type de list box affiché (cf. sections suivantes).

    You can use the lk inherited constant to mimic the current appearance of the list box (e.g., font color, background color, font style, etc.).

    List box de type sélection

    To determine which rows are selected, you have to check whether they are included in the set indicated in the Highlight Set property of the list box. You can then define the appearance of selected rows using one or more of the relevant color or style expression property.

    N'oubliez pas que les expressions sont automatiquement réévaluées à chaque fois que :

    • la sélection dans la list box est modifiée,
    • la list box prend ou perd le focus,
    • la fenêtre formulaire contenant la list box passe au premier plan ou quitte le premier plan.

    List box de type tableau

    You have to parse the Boolean array Variable or Expression associated with the list box to determine whether rows are selected or not selected.

    You can then define the appearance of selected rows using one or more of the relevant color or style array property.

    Note that list box arrays used for defining the appearance of selected rows must be recalculated during the On Selection Change form event; however, you can also modify these arrays based on the following additional form events:

    • On Getting Focus (list box property)
    • On Losing Focus (list box property)
    • On Activate (form property)
    • On Deactivate (form property) ...depending on whether and how you want to visually represent changes of focus in selections.
    Exemple

    Vous avez choisi de cacher le surlignage système et souhaitez représenter les sélections dans la list box à l'aide d'une couleur de fond verte, comme dans cet exemple :

    For an array type list box, you need to update the Row Background Color Array by programming. Dans le formulaire JSON, vous avez défini le Tableau couleurs de fond suivant pour la list box :

        "rowFillSource": "_ListboxBackground",

    Dans la méthode objet de la list box, vous pouvez écrire :

     Case of
    :(FORM event.code=On Selection Change)
    $n:=Size of array(LB_Arrays)
    ARRAY LONGINT(_ListboxBackground;$n) // row background colors
    For($i;1;$n)
    If(LB_Arrays{$i}=True) // selected
    _ListboxBackground{$i}:=0x0080C080 // green background
    Else // not selected
    _ListboxBackground{$i}:=lk inherited
    End if
    End for
    End case

    For a selection type list box, to produce the same effect you can use a method to update the Background Color Expression based on the set specified in the Highlight Set property.

    Par exemple, dans le formulaire JSON, vous avez défini l'ensemble surlignage et l'expression de couleur de fond suivants pour la list box :

        "highlightSet": "$SampleSet",
    "rowFillSource": "UI_SetColor",

    You can write in the UI_SetColor method:

     If(Is in set("$SampleSet"))
    $color:=0x0080C080 // green background
    Else
    $color:=lk inherited
    End if

    $0:=$color

    In hierarchical list boxes, break rows cannot be highlighted when the Hide selection highlight option is checked. Comme il n'est pas possible d'avoir des couleurs distinctes pour les en-têtes de même niveau, il n'y a aucun moyen de surligner une ligne de rupture spécifique par programmation.

    Gestion des tris

    Le tri dans une list box peut être standard ou personnalisé. Lorsqu'une colonne de list box est triée, toutes les autres colonnes sont toujours synchronisées automatiquement.

    Tri standard

    Par défaut, une list box gère automatiquement les tris standard des colonnes en cas de clic sur l’en-tête. Un tri standard est un tri alphanumérique des valeurs de la colonne, alternativement croissant / décroissant lors de clics successifs.

    You can enable or disable standard user sorts by disabling the Sortable property of the list box (enabled by default).

    La prise en charge du tri standard dépend du type de list box :

    Type de list boxPrise en charge du tri standardCommentaires
    Collection d'objetsOui
  • "This.a" or "This.a.b" columns are sortable.
  • The list box source property must be an assignable expression.
  • Collection de valeurs scalairesNonUse custom sort with orderBy() function
    Entity selectionOui
  • The list box source property must be an assignable expression.
  • Supported: sorts on object attribute properties (e.g. "This.data.city" when "data" is an object attribute)
  • Supported: sorts on related attributes (e.g. "This.company.name")
  • Not supported: sorts on object attribute properties through related attributes (e.g. "This.company.data.city"). For this, you need to use custom sort with orderByFormula() function (see example below)
  • Sélection couranteOuiOnly simple expressions are sortable (e.g. [Table_1]Field_2)
    Sélection temporaireNon
    TableauxOuiLes colonnes liées à des tableaux d'images et de pointeurs ne sont pas triables

    Tri personnalisé

    The developer can set up custom sorts, for example using the LISTBOX SORT COLUMNS command and/or combining the On Header Click and On After Sort form events and relevant 4D commands.

    Les tris personnalisés vous permettent de :

    Exemple

    Vous souhaitez trier une list box en utilisant les valeurs d'une propriété stockée dans un attribut d'objet lié. Vous avez la structure suivante :

    You design a list box of the entity selection type, bound to the Form.child expression. In the On Load form event, you execute Form.child:=ds.Child.all().

    Vous affichez deux colonnes :

    Child nameParent's nickname
    This.nameThis.parent.extra.nickname

    Si vous voulez trier la list box en utilisant les valeurs de la deuxième colonne, vous devez écrire :

    If (Form event code=On Header Click)
    Form.child:=Form.child.orderByFormula("This.parent.extra.nickname"; dk ascending)
    End if

    Variable d'en-tête de colonne

    The value of the column header variable allows you to manage additional information: the current sort of the column (read) and the display of the sort arrow.

    • Si la variable est définie sur 0, la colonne n'est pas triée et la flèche de tri n'est pas affichée.\

    • If the variable is set to 1, the column is sorted in ascending order and the sort arrow is displayed.

    • If the variable is set to 2, the column is sorted in descending order and the sort arrow is displayed.

    Only declared or dynamic variables can be used as header column variables. Other kinds of expressions such as Form.sortValue are not supported.

    Vous pouvez définir la valeur de la variable (par exemple, Header2:=2) afin de "forcer" l'affichage de la flèche de tri. Le tri de la colonne lui-même n'est pas modifié dans ce cas ; c'est au développeur de s'en charger.

    The OBJECT SET FORMAT command offers specific support for icons in list box headers, which can be useful when you want to work with a customized sort icon.

    Gestion des styles et des couleurs

    Vous disposez de plusieurs possibilités pour définir des couleurs de fond, des couleurs de police et des styles de police dans les list box :

    Priority & inheritance

    Des principes de priorité et d'héritage sont observés lorsqu’une même propriété est définie à plusieurs niveaux.

    Niveau de prioritéEmplacement du paramètre
    priorité élevéeCellule (si texte multistyle)
    Tableaux/Méthodes colonne
    Tableaux/Méthodes list box
    Propriétés de colonne
    Propriétés de list box
    priorité basseMeta Info expression (pour les list box de type collection ou entity selection)

    Par exemple, si vous définissez un style de caractères dans les propriétés de la list box et un autre via un tableau de styles pour la colonne, ce dernier sera pris en compte.

    For each attribute (style, color and background color), an inheritance is implemented when the default value is used:

    • pour les attributs des cellules : valeurs d’attributs des lignes
    • pour les attributs des lignes : valeurs d’attributs des colonnes
    • pour les attributs des colonnes : valeurs d’attributs de la list box

    This way, if you want an object to inherit the attribute value from a higher level, you can use pass the lk inherited constant (default value) to the definition command or directly in the element of the corresponding style/color array. For example, given an array list box containing a standard font style with alternating colors:

    Vous effectuez les modifications suivantes :

    • change the background of row 2 to red using the Row Background Color Array property of the list box object,
    • change the style of row 4 to italics using the Row Style Array property of the list box object,
    • two elements in column 5 are changed to bold using the Row Style Array property of the column 5 object,
    • the 2 elements for column 1 and 2 are changed to dark blue using the Row Background Color Array property for the column 1 and 2 objects:

    Pour restaurer l’apparence initiale de la list box, il suffit de :

    • pass the lk inherited constant in element 2 of the background color arrays for columns 1 and 2: then they inherit the red background color of the row.
    • pass the lk inherited constant in elements 3 and 4 of the style array for column 5: then they inherit the standard style, except for element 4, which changes to italics as specified in the style array of the list box.
    • pass the lk inherited constant in element 4 of the style array for the list box in order to remove the italics style.
    • pass the lk inherited constant in element 2 of the background color array for the list box in order to restore the original alternating color of the list box.

    Utiliser des tableaux et des expressions

    Selon le type de list box, vous pouvez utiliser différentes propriétés pour personnaliser les couleurs, les styles et l'affichage des lignes :

    PropriétéList box tableauListe box sélectionList box collection ou entity selection
    Couleur de fondRow Background Color ArrayBackground Color ExpressionBackground Color Expression or Meta info expression
    Couleur de la policeRow Font Color ArrayFont Color ExpressionFont Color Expression or Meta info expression
    Style de policeRow Style ArrayStyle ExpressionStyle Expression or Meta info expression
    AffichageRow Control Array-*

    Gestion des impressions

    Two printing modes are available: preview mode - which can be used to print a list box like a form object, and advanced mode - which lets you control the printing of the list box object itself within the form. A noter que l'apparence "Impression" est proposée pour les list box dans l'éditeur de formulaires.

    Mode prévisualisation

    Printing a list box in preview mode consists of directly printing the list box and the form that contains it using the standard print commands or the Print menu command. La list box est imprimée dans l’état où elle se trouve dans le formulaire. Ce mode ne permet pas de contrôler précisément l’impression de l’objet ; en particulier, il ne permet pas d’imprimer toutes les lignes d’une list box contenant plus de lignes qu’elle ne peut en afficher.

    Mode avancé

    In this mode, the printing of list boxes is carried out by programming, via the Print object command (project forms and table forms are supported). The LISTBOX GET PRINT INFORMATION command is used to control the printing of the object.

    Dans ce mode :

    • La hauteur de l’objet list box est automatiquement réduite lorsque le nombre de lignes à imprimer est inférieur à la hauteur d’origine de l’objet (il n’y a pas de lignes "vides" imprimées). En revanche, la hauteur n’augmente pas automatiquement en fonction du contenu de l’objet. The size of the object actually printed can be obtained via the LISTBOX GET PRINT INFORMATION command.
    • L'objet list box est imprimé "tel quel", c’est-à-dire en tenant compte de ses paramètres d’affichage courants : visibilité des en-têtes et des grilles, lignes affichées et masquées, etc. These parameters also include the first row to be printed: if you call the OBJECT SET SCROLL POSITION command before launching the printing, the first row printed in the list box will be the one designated by the command.
    • An automatic mechanism facilitates the printing of list boxes that contain more rows than it is possible to display: successive calls to Print object can be used to print a new set of rows each time. The LISTBOX GET PRINT INFORMATION command can be used to check the status of the printing while it is underway.

    List box hiérarchiques

    Une list box hiérarchique est une list box dans laquelle le contenu de la première colonne apparaît sous forme hiérarchique. Ce type de représentation est adapté à la présentation d’informations comportant des valeurs répétées et/ou hiérarchiquement dépendantes (pays/région/ville...).

    Only array type list boxes can be hierarchical.

    Les list box hiérarchiques constituent un mode de représentation particulier des données, mais ne modifient pas la structure de ces données (les tableaux). Les list box hiérarchiques sont gérées exactement de la même manière que les list box non hiérarchiques.

    Définir une hiérarchie

    Pour définir une list box hiérarchique, vous disposez de trois possibilités :

    • Configurer manuellement les éléments hiérarchiques via la liste des propriétés dans l’éditeur de formulaires (ou éditer le formulaire JSON).
    • Générer visuellement la hiérarchie à l’aide du pop up menu de gestion des list box, dans l’éditeur de formulaires.
    • Use the LISTBOX SET HIERARCHY and LISTBOX GET HIERARCHY commands, described in the 4D Language Reference manual.

    Propriété List box hiérarchique

    Cette propriété permet de définir que la list box doit être affichée sous forme hiérarchique. In the JSON form, this feature is triggered when the column dataSource property value is an array, i.e. a collection.

    Additional options (Variable 1...10) are available when the Hierarchical List Box option is selected, corresponding to each element of the dataSource array to use as break column. A chaque saisie d’une valeur dans un champ, une nouvelle ligne est ajoutée. Jusqu’à 10 variables peuvent être définies. Ces variables définissent les niveaux hiérarchiques à afficher dans la première colonne.

    La première variable correspond toujours au nom de variable de la première colonne de la list box (les deux valeurs sont automatiquement liées). Cette première variable est toujours visible et saisissable. Par exemple : pays. La seconde variable est également toujours visible et saisissable, elle définit le deuxième niveau hiérarchique. Par exemple : régions. A partir du troisième champ, chaque variable dépend de celle qui la précède. Par exemple : départements, villes, etc. Un maximum de dix niveaux hiérarchiques peut être défini. Si vous effacez une valeur, l’ensemble de la liste hiérarchique définie remonte d’un niveau.

    La dernière variable n’est jamais hiérarchique même si plusieurs valeurs identiques existent à ce niveau. Par exemple, en reprenant la configuration illustrée ci-dessus, imaginons que tab1 contienne les valeurs A A A B B B, tab2 les valeurs 1 1 1 2 2 2 et tab3 les valeurs X X Y Y Y Z. Dans ce cas, A, B, 1 et 2 pourront apparaître sous forme contractée, mais pas X et Y :

    Ce principe n’est pas appliqué lorsqu’une seule variable est définie dans la hiérarchie : dans ce cas, les valeurs identiques pourront être groupées.

    Si vous définissez une hiérarchie basée sur les premières colonnes d’une list box existante, vous devez ensuite supprimer ou masquer ces colonnes (à l’exception de la première) sinon elles apparaîtront en double dans la list box. Si vous définissez la hiérarchie via le pop up menu de l’éditeur (cf. ci-dessous), les colonnes superflues sont automatiquement supprimées de la list box.

    Créer une hiérarchie via le menu contextuel

    When you select at least one column in addition to the first one in a list box object (of the array type) in the form editor, the Create hierarchy command is available in the context menu:

    Cette commande est un raccourci pour définir une hiérarchie. Lorsque vous la choisissez, les actions suivantes sont effectuées :

    • The Hierarchical list box option is checked for the object in the Property List.
    • Les variables des colonnes sont utilisées pour définir la hiérarchie. Elles remplacent les variables éventuellement déjà définies.
    • Les colonnes sélectionnées n’apparaissent plus dans la list box (à l’exception du titre de la première).

    Exemple : soit une list box dont les premières colonnes contiennent Pays, Région, Ville et Population. When Country, Region and City are selected, if you choose Create hierarchy in the context menu, a three-level hierarchy is created in the first column, columns 2 and 3 are removed and the Population column becomes the second:

    Annuler une hiérarchie

    When the first column is selected and already specified as hierarchical, you can use the Cancel hierarchy command. Lorsque vous choisissez cette commande, les actions suivantes sont effectuées :

    • The Hierarchical list box option is deselected for the object,
    • Les niveaux hiérarchiques 2 à n sont supprimés et transformés en colonnes ajoutées dans la list box.

    Principes de fonctionnement

    A la première ouverture d’un formulaire contenant une list box hiérarchique, par défaut toutes les lignes sont déployées.

    Une ligne de rupture et un "noeud" hiérarchique sont automatiquement ajoutés dans la list box lorsque des valeurs sont répétées dans les tableaux. Par exemple, imaginons une list box contenant quatre tableaux définissant des villes, chaque ville étant caractérisée par un pays, une région, un nom et un nombre d’habitants :

    Si cette list box est affichée sous forme hiérarchique (les trois premiers tableaux étant inclus dans la hiérarchie), vous obtenez :

    Les tableaux ne sont pas triés avant la construction de la hiérarchie. If, for example, an array contains the data AAABBAACC, the hierarchy obtained is: > A > B > A > C

    Pour déployer ou contracter un "nœud" hiérarchique, cliquez dessus. If you Alt+click (Windows) or Option+click (macOS) on the node, all its sub-elements will be expanded or collapsed as well. These operations can also be carried out by programming using the LISTBOX EXPAND and LISTBOX COLLAPSE commands.

    Lorsque des valeurs de type date ou heure sont incluses dans une list box hiérarchique, elles sont affichées dans un format normalisé.

    Gestion des tris dans les list box hiérarchiques

    Dans une list box en mode hiérarchique, un tri standard (effectué suite à un clic dans un en-tête de colonne de la list box) est toujours construit de la manière suivante :

    • En premier lieu, tous les niveaux de la colonne hiérarchique (première colonne) sont automatiquement triés par ordre croissant.
    • Le tri est ensuite effectué par ordre croissant ou décroissant (suivant l’action utilisateur) sur les valeurs de la colonne où le clic a eu lieu.
    • Toutes les colonnes sont synchronisées.
    • Lors des tris ultérieurs des colonnes non hiérarchiques de la list box, seul le dernier niveau de la première colonne est trié. Il est possible de modifier le tri de cette colonne en cliquant sur son en-tête.

    Soit par exemple la list box suivante, dans laquelle aucun tri spécifique n’est défini :

    Si vous cliquez sur l’en-tête "Population" afin de trier les populations par ordre croissant (ou alternativement décroissant), les données apparaissent ainsi :

    As for all list boxes, you can disable the standard sort mechanism and manage sorts using programming.

    Gestion des sélections et des positions dans les list box hiérarchiques

    Une list box hiérarchique affiche un nombre variable de lignes à l’écran en fonction de l’état déployé/contracté des nœuds hiérachiques. Cela ne signifie pas pour autant que le nombre de lignes des tableaux varie. Seul l’affichage est modifié, pas les données. Il est important de comprendre ce principe car la gestion programmée des list box hiérarchiques se base toujours sur les données des tableaux, pas sur les données affichées. En particulier, les lignes de rupture ajoutées automatiquement ne sont pas prises en compte dans les tableaux d’options d’affichage (cf. ci-dessous).

    Examinons par exemple les tableaux suivants :

    Si ces tableaux sont représentés hiérarchiquement, la ligne "Quimper" ne sera pas affichée sur la deuxième ligne mais sur la quatrième, à cause des deux lignes de rupture ajoutées :

    Quelle que soit la manière dont les données sont affichées dans la list box (hiérarchique ou non-hiérarchique), si vous souhaitez passer la ligne contenant "Quimper" en gras, vous devrez utiliser l’instruction TabStyle{2} = bold. Seule la position de la ligne dans les tableaux est prise en compte.

    Ce principe est mis en oeuvre pour les tableaux internes permettant de gérer :

    • les couleurs

    • les couleurs de fond

    • les styles

    • les lignes masquées

    • les sélections

    Par exemple, si vous voulez sélectionner la ligne contenant Rennes, vous devez passer :

     ->MyListbox{3}:=True

    Non-hierarchical representation: Hierarchical representation:

    Si une ou plusieurs lignes sont masquées du fait que leurs parents ont été contractés, elles ne sont plus sélectionnées. Seules les lignes visibles (directement ou suite à un défilement) sont sélectionnables. Autrement dit, les lignes ne peuvent pas être à la fois sélectionnées et cachées.

    As with selections, the LISTBOX GET CELL POSITION command will return the same values for a hierarchical list box and a non-hierarchical list box. This means that in both of the examples below, LISTBOX GET CELL POSITION will return the same position: (3;2).

    Non-hierarchical representation:

    Hierarchical representation:

    Lorsque toutes les lignes d’une sous-hiérarchie sont masquées, la ligne de rupture est automatiquement masquée. Dans l’exemple ci-dessus, si les lignes 1 à 3 sont masquées, la ligne de rupture "Bretagne" n’apparaîtra pas.

    Lignes de rupture

    If the user selects a break row, LISTBOX GET CELL POSITION returns the first occurrence of the row in the corresponding array. Dans le cas suivant :

    ... LISTBOX GET CELL POSITION returns (2;4). To select a break row by programming, you will need to use the LISTBOX SELECT BREAK command.

    Les lignes de rupture ne sont pas prises en compte dans les tableaux internes permettant de gérer l’apparence graphique des list box (styles et couleurs). Il est toutefois possible de modifier ces caractéristiques pour les lignes de rupture via les commandes de gestion graphique des objets. Il suffit pour cela d’exécuter ces commandes appropriées sur les tableaux constituant la hiérarchie.

    Soit par exemple la list box suivante (les noms des tableaux associés sont précisés entre parenthèses) :

    Non-hierarchical representation:

    Hierarchical representation:

    In hierarchical mode, break levels are not taken into account by the style modification arrays named tStyle and tColors. Pour modifier la couleur ou le style des niveaux de rupture, vous devez exécuter les instructions suivantes :

     OBJECT SET RGB COLORS(T1;0x0000FF;0xB0B0B0)
    OBJECT SET FONT STYLE(T2;Bold)

    Dans ce contexte, seule la syntaxe utilisant la variable tableau peut fonctionner avec les commandes de propriété d’objet car les tableaux n’ont alors pas d’objet associé.

    Résultat:

    Gestion optimisée du déployer/contracter

    You can optimize hierarchical list boxes display and management using the On Expand and On Collapse form events.

    Une list box hiérarchique est construite à partir du contenu des tableaux qui la constituent, elle ne peut donc être affichée que lorsque tous les tableaux sont chargés en mémoire. This makes it difficult to build large hierarchical list boxes based on arrays generated from data (through the SELECTION TO ARRAY command), not only because of the display speed but also the memory used.

    Using the On Expand and On Collapse form events can overcome these constraints: for example, you can display only part of the hierarchy and load/unload the arrays on the fly, based on user actions. In the context of these events, the LISTBOX GET CELL POSITION command returns the cell where the user clicked in order to expand or collapse a row.

    Dans ce cas, le remplissage et le vidage des tableaux doivent être effectués par le code. Les principes à mettre en oeuvre sont :

    • A l’affichage de la listbox, seul le premier tableau doit être rempli. However, you must create a second array with empty values so that the list box displays the expand/collapse buttons:

    • When a user clicks on an expand button, you can process the On Expand event. The LISTBOX GET CELL POSITION command returns the cell concerned and lets you build the appropriate hierarchy: you fill the first array with the repeated values and the second with the values sent from the SELECTION TO ARRAY command and you insert as many rows as needed in the list box using the LISTBOX INSERT ROWS command.

    • When a user clicks on a collapse button, you can process the On Collapse event. The LISTBOX GET CELL POSITION command returns the cell concerned: you remove as many rows as needed from the list box using the LISTBOX DELETE ROWS command.

    Tableaux d'objets dans les colonnes

    Les colonnes de list box peuvent être associées à des tableaux d'objets. Comme les tableaux d'objets peuvent contenir des données de types différents, cette puissante fonctionnalité vous permet de saisir et d'afficher divers types de valeurs dans les lignes d'une même colonne, ainsi que d'utiliser divers objets d'interface (widgets). Par exemple, vous pouvez placer une zone de saisie de texte dans la première ligne, une case à cocher dans la seconde, et une liste déroulante dans la troisième. Les tableaux d'objets vous donnent également accès à des widgets supplémentaires, tels que des boutons ou des sélecteurs de couleurs (color picker).

    La list box suivante a été définie à l'aide d'un tableau d'objets :

    Configurer une colonne tableau d'objets

    To assign an object array to a list box column, you just need to set the object array name in either the Property list ("Variable Name" field), or using the LISTBOX INSERT COLUMN command, like with any array-based column. Dans la Liste des propriétés, vous pouvez sélectionner Objet comme "Type de variable" pour la colonne :

    Les propriétés standard liées aux coordonnées, taille et style sont disponibles pour les colonnes de type objet. Elles peuvent être gérées à l'aide de la Liste des propriétés, ou en programmant les attributs de style, visibilité, couleur de police et de fond de chaque ligne de colonne objet de la list box. Ce type de colonne peut également être masqué.

    Toutefois, le thème Source de données n'est pas disponible pour les colonnes objet des list box. En fait, le contenu de chaque cellule de la colonne est basé sur les attributs présents dans l'élément correspondant du tableau d'objets. Chaque élément du tableau peut définir :

    le type de valeur (obligatoire) : texte, couleur, événement, etc. la valeur elle-même (optionnel) : utilisé aussi bien pour la saisie que pour l'affichage. le mode d'affichage du contenu de la cellule (optionnel) : bouton, liste, etc. des paramètres supplémentaires (optionnel) : dépend du type de valeur Pour définir ces propriétés, vous devez placer les attributs adéquats dans l'objet (la liste des attributs disponibles est fournie ci-dessous). Par exemple, vous pouvez écrire "Hello World!" dans une colonne objet à l'aide de ce simple code :

    ARRAY OBJECT(obColumn;0) //column array
    C_OBJECT($ob) //first element
    OB SET($ob;"valueType";"text") //defines the value type (mandatory)
    OB SET($ob;"value";"Hello World!") //defines the value
    APPEND TO ARRAY(obColumn;$ob)

    Il n'est pas possible de choisir un format d'affichage et/ou un filtre de saisie pour les colonnes objet. Ces paramètres sont automatiquement définis en fonction du type de valeur.

    valueType et affichage des données

    Lorsqu'une colonne de list box est associée à un tableau d'objets, l'affichage, la saisie et l'édition des cellules sont basées sur l'attribut valueType présent dans chaque élément du tableau. Les valeurs valueType prises en charge sont les suivantes :

    • "text" : pour une valeur texte
    • "real": for a numeric value that can include separators like a \<space>, <.>, or <,>
    • "integer" : pour une valeur entière
    • "boolean" : pour une valeur True/False
    • "color" : pour définir une couleur de fond
    • "event" : pour afficher un bouton avec un libellé.

    4D uses default widgets with regards to the "valueType" value (i.e., a "text" is displayed as a text input widget, a "boolean" as a check box), but alternate displays are also available through options (e.g., a real can also be represented as a drop-down menu). Le tableau suivant indique l'affichage par défaut ainsi que les variations possibles pour chaque type de valeur :

    valueTypeFormat défautWidget(s) alternatif(s)
    textzone de saisie de textemenu déroulant (enumération obligatoire) ou combo box (enumération)
    réelzone de saisie de texte contrôlée (nombre et séparateurs)menu déroulant (enumération obligatoire) ou combo box (enumération)
    entierzone de saisie de texte contrôlée (nombre)menu déroulant (enumération obligatoire) ou combo box (enumération) ou case à cocher trois états
    booleancase à cochermenu déroulant (enumération obligatoire)
    colorcouleur de fondtext
    eventbouton avec libellé
    Tous les widgets peuvent associer un unit toggle button ou ellipsis button à la cellule.

    Vous définissez l'affichage de la cellule et les variations à l'aide d'attributs spécifiques dans chaque objet (voir ci-dessous).

    Formats d'affichage et filtres de saisie

    Il n'est pas possible de choisir un format d'affichage et/ou un filtre de saisie pour les colonnes objet des list box. Ils sont automatiquement définis en fonction du type de valeur. Ils sont listés dans le tableau suivant :

    Value typeFormat défautContrôle de saisie
    textle même que celui de l'objetpas de contrôle (tout caractère accepté)
    réelle même que celui de l'objet (utilisation du séparateur décimal système)"0-9" et "." et "-"
    "0-9" and "." if min>=0
    entierle même que celui de l'objet"0-9" et "-"
    "0-9" if min>=0
    Booleancase à cocherN/A
    colorN/AN/A
    eventN/AN/A

    Attributs

    Chaque élément du tableau d'objets est un objet qui peut contenir un ou plusieurs attributs qui définiront le contenu de la cellule et l'affichage des données (voir exemple ci-dessus).

    L'unique attribut obligatoire est "valueType" et ses valeurs acceptées sont "text", "real", "integer", "boolean", "color" et "event". Le tableau suivant liste tous les attributs acceptés dans les tableaux d'objets des list box, suivant la valeur de "valueType" (tout autre attribut est ignoré). Les formats d'affichage et des exemples sont fournis ci-dessous.

    valueTypetextréelentierbooleancolorevent
    AttributsDescription
    valuevaleur de la cellule (saisie ou affichage)xxx
    minvaleur minimumxx
    maxvaleur maximumxx
    behaviorvaleur "threeStates"x
    requiredListmenu déroulant défini dans l'objetxxx
    choiceListcombo box défini dans l'objetxxx
    requiredListReferenceRefList 4D, dépend de la valeur de "saveAs"xxx
    requiredListNamenom d'énumération 4D, dépend de la valeur de "saveAs"xxx
    saveAs"reference" ou "value"xxx
    choiceListReferenceRefList 4D, affiche une combo boxxxx
    choiceListNamenom d'énumération 4D, affiche une combo boxxxx
    unitListtableau de X élémentsxxx
    unitReferenceindice de l'élément sélectionnéxxx
    unitsListReferenceRefList 4D pour les unitésxxx
    unitsListNamenom d'énumération 4D pour les unitésxxx
    alternateButtonajouter un bouton alternatifxxxxx

    value

    La valeur des cellules est stockée dans l'attribut "value". Cet attribut est utilisé pour la saisie (entrée) et pour l'affichage (sortie). Il peut également être utilisé pour définir des valeurs par défaut lors de l'utilisation des listes (voir ci-dessous).

     ARRAY OBJECT(obColumn;0) //column array
    C_OBJECT($ob1)
    $entry:="Hello world!"
    OB SET($ob1;"valueType";"text")
    OB SET($ob1;"value";$entry) // if the user enters a new value, $entry will contain the edited value
    C_OBJECT($ob2)
    OB SET($ob2;"valueType";"real")
    OB SET($ob2;"value";2/3)
    C_OBJECT($ob3)
    OB SET($ob3;"valueType";"boolean")
    OB SET($ob3;"value";True)

    APPEND TO ARRAY(obColumn;$ob1)
    APPEND TO ARRAY(obColumn;$ob2)
    APPEND TO ARRAY(obColumn;$ob3)

    La valeur Null est acceptée, elle définit une cellule vide.

    min et max

    Lorsque le "valueType" est "real" ou "integer", l'objet accepte également les attributs min et max avec les valeurs appropriées (les valeurs doivent être du même type que valueType).

    Ces attributs peuvent être utilisés pour contrôler la plage de valeurs d'entrée. Lorsqu'une cellule est validée (lorsqu'elle perd le focus), si la valeur de saisie est inférieure à la valeur minimale ou supérieure à la valeur maximale, elle est rejetée. Dans ce cas, la valeur précédente est conservée et une astuce affiche une explication.

     C_OBJECT($ob3)
    $entry3:=2015
    OB SET($ob3;"valueType";"integer")
    OB SET($ob3;"value";$entry3)
    OB SET($ob3;"min";2000)
    OB SET($ob3;"max";3000)

    behavior

    L'attribut behavior propose des variations de la représentation standard des valeurs. Une seule variation est possible :

    AttributValeur(s) disponible(s)valueType(s)Description
    behaviorthreeStatesentierReprésente une valeur numérique sous forme de case à cocher à trois états.
    2=intermédiaire, 1=cochée, 0=non cochée, -1=invisible, -2=non cochée désactivée, -3=cochée désactivée, -4=intermédiaire désactivée
     C_OBJECT($ob3)
    OB SET($ob3;"valueType";"integer")

    OB SET($ob3;"value";-3)
    C_OBJECT($ob4)
    OB SET($ob4;"valueType";"integer")
    OB SET($ob4;"value";-3)
    OB SET($ob4;"behavior";"threeStates")

    requiredList et choiceList

    Lorsqu'un attribut "choiceList" ou "requiredList" est présent dans l'objet, la zone de saisie de texte est remplacée par une liste déroulante ou une combo box, en fonction de l'attribut :

    • Si l'attribut est "choiceList", la cellule est affichée sous forme de combo box. Cela signifie que l'utilisateur peut sélectionner ou saisir une valeur.
    • Si l'attribut est "requiredList", la cellule est affichée sous forme de liste déroulante. Cela signifie que l'utilisateur peut uniquement sélectionner une des valeurs de la liste.

    Dans les deux cas, vous pouvez utiliser un attribut "value" pour présélectionner une valeur dans le widget.

    Les valeurs du widget sont définies via un tableau. Si vous souhaitez associer le widget à une énumération 4D existante, vous devez utiliser les attributs "requiredListReference", "requiredListName", "choiceListReference" ou "choiceListName".

    Exemples :

    • Vous voulez afficher une liste déroulante avec juste deux options, "Open" ou "Closed". "Closed" doit être présélectionné :
        ARRAY TEXT($RequiredList;0)
    APPEND TO ARRAY($RequiredList;"Open")
    APPEND TO ARRAY($RequiredList;"Closed")
    C_OBJECT($ob)
    OB SET($ob;"valueType";"text")
    OB SET($ob;"value";"Closed")
    OB SET ARRAY($ob;"requiredList";$RequiredList)

    • Vous voulez accepter toute valeur entière, mais afficher une combo box contenant les valeurs les plus communes :
        ARRAY LONGINT($ChoiceList;0)
    APPEND TO ARRAY($ChoiceList;5)
    APPEND TO ARRAY($ChoiceList;10)
    APPEND TO ARRAY($ChoiceList;20)
    APPEND TO ARRAY($ChoiceList;50)
    APPEND TO ARRAY($ChoiceList;100)
    C_OBJECT($ob)
    OB SET($ob;"valueType";"integer")
    OB SET($ob;"value";10) //10 as default value
    OB SET ARRAY($ob;"choiceList";$ChoiceList)

    requiredListName et requiredListReference

    Les attributs "requiredListName" et "requiredListReference" vous permettent d'utiliser, dans une cellule de list box, une énumération définie dans 4D soit en mode Développement (via l'éditeur d'Enumérations de la Boîte à outils) soit par programmation (à l'aide de la commande New list). La cellule sera alors affichée sous forme de liste déroulante. Cela signifie que l'utilisateur pourra uniquement choisir une des valeurs fournies dans la liste.

    Utilisez "requiredListName" ou "requiredListReference" en fonction de la provenance de la liste : si la liste provient de la Boîte à outils, utilisez son nom ; sinon, si la liste a été définie par programmation, passez sa référence. Dans les deux cas, vous pouvez utiliser un attribut "value" pour présélectionner une valeur dans le widget.

    • Si vous souhaitez définir des valeurs d'énumération via un simple tableau, vous pouvez utiliser l'attribut "requiredList".
    • Si la liste contient du texte représentant des valeurs réelles, le séparateur décimal doit être le point ("."), quels que soient les paramètres locaux, ex : "17.6" "1234.456".

    Exemples :

    • Vous voulez afficher une liste déroulante basée sur une énumération nommée "colors" définie dans la Boîte à outils (contenant les valeurs "bleu", "jaune" et "vert"), la stocker en tant que valeur et afficher "bleu" par défaut :

        C_OBJECT($ob)
    OB SET($ob;"valueType";"text")
    OB SET($ob;"saveAs";"value")
    OB SET($ob;"value";"blue")
    OB SET($ob;"requiredListName";"colors")

    • Vous voulez afficher une liste déroulante basée sur une liste créée par programmation, et la stocker en tant que référence :
        <>List:=New list
    APPEND TO LIST(<>List;"Paris";1)
    APPEND TO LIST(<>List;"London";2)
    APPEND TO LIST(<>List;"Berlin";3)
    APPEND TO LIST(<>List;"Madrid";4)
    C_OBJECT($ob)
    OB SET($ob;"valueType";"integer")
    OB SET($ob;"saveAs";"reference")
    OB SET($ob;"value";2) //displays London by default
    OB SET($ob;"requiredListReference";<>List)
    ![](../assets/en/FormObjects/listbox_column_objectArray_cities.png)

    choiceListName et choiceListReference

    Les attributs "choiceListName" et "choiceListReference" permettent d'utiliser, dans une cellule de list box, une énumération définie dans 4D soit en mode Développement (via l'éditeur de la Boîte à outils) soit par programmation (à l'aide de la commande New list). La cellule sera alors affichée sous forme de combo box, ce qui signifie que l'utilisateur pourra choisir une des valeurs de la liste ou en saisir une.

    Utilisez "choiceListName" ou "choiceListReference" en fonction de la provenance de la liste : si la liste provient de la Boîte à outils, utilisez son nom ; sinon, si la liste a été définie par programmation, passez sa référence. Dans les deux cas, vous pouvez utiliser un attribut "value" pour présélectionner une valeur dans le widget.

    • Si vous souhaitez définir des valeurs d'énumération via un simple tableau, vous pouvez utiliser l'attribut "choiceList".
    • Si la liste contient du texte représentant des valeurs réelles, le séparateur décimal doit être le point ("."), quels que soient les paramètres locaux, ex : "17.6" "1234.456".

    Voici un exemple :

    Vous voulez afficher une combo box basée sur une énumération nommée "colors" définie dans la Boîte à outils (contenant les valeurs "bleu", "jaune" et "vert") et afficher "vert" par défaut :

     C_OBJECT($ob)
    OB SET($ob;"valueType";"text")
    OB SET($ob;"value";"vert")
    OB SET($ob;"choiceListName";"colors")

    unitsList, unitsListName, unitsListReference et unitReference

    You can use specific attributes to add units associated with cell values (e.g.: "10 cm", "20 pixels", etc.). Pour définir une liste d'unités, vous pouvez utiliser l'un des attributs suivants :

    • "unitsList" : un tableau contenant les x éléments définissant les unités disponibles (ex : "cm", "pouces", "km", "miles", etc.). Utilisez cet attribut pour définir des unités dans l'objet.
    • "unitsListReference" : une référence de liste 4D contenant les unités disponibles. Use this attribute to define units with a 4D list created with the New list command.
    • "unitsListName" : un nom d'énumération 4D créée en mode Développement contenant les unités disponibles. Utilisez cet attribut pour définir des unités à l'aide d'une énumération 4D créée dans la Boîte à outils.

    Quel que soit son mode de définition, la liste d'unités peut être associée à l'attribut suivant :

    • "unitReference" : une valeur simple contenant l'indice (de 1 à x) de l'élément sélectionné dans la liste de valeurs "unitList", "unitsListReference" ou "unitsListName".

    L'unité courante est affichée sous forme de bouton affichant successivement les valeurs de "unitList", "unitsListReference" ou "unitsListName" à chaque clic (par exemple "pixels" -> "lignes" -> "cm" -> "pixels" -> etc.)

    Voici un exemple :

    Vous souhaitez définir une valeur de saisie numérique suivie d'une unité parmi deux possibles : "cm" ou "pixels". La valeur courante est "2" + "cm". Vous utilisez des valeurs définies directement dans l'objet (attribut "unitsList") :

    ARRAY TEXT($_units;0)
    APPEND TO ARRAY($_units;"cm")
    APPEND TO ARRAY($_units;"pixels")
    C_OBJECT($ob)
    OB SET($ob;"valueType";"integer")
    OB SET($ob;"value";2) // 2 "units"
    OB SET($ob;"unitReference";1) //"cm"
    OB SET ARRAY($ob;"unitsList";$_units)

    alternateButton

    If you want to add an ellipsis button [...] to a cell, you just need to pass the "alternateButton" with the True value in the object. Le bouton sera automatiquement affiché dans la cellule.

    When this button is clicked by a user, an On Alternate Click event will be generated, and you will be able to handle it however you want (see the "Event management" paragraph for more information).

    Voici un exemple :

    C_OBJECT($ob1)
    $entry:="Hello world!"
    OB SET($ob;"valueType";"text")
    OB SET($ob;"alternateButton";True)
    OB SET($ob;"value";$entry)

    valueType color

    L'attribut "valueType" de valeur "color" vous permet d'afficher soit une couleur, soit un texte.

    • Si la valeur est un nombre, un rectangle de couleur est dessiné à l'intérieur de la cellule. Voici un exemple :

      C_OBJECT($ob4)
      OB SET($ob4;"valueType";"color")
      OB SET($ob4;"value";0x00FF0000)

    • If the value is a text, then the text is displayed (e.g.: "value";"Automatic").

    valueType event

    The "event" valueType displays a simple button that generates an On Clicked event when clicked. Aucune donnée ou valeur ne peut être passée ou retournée.

    Optionnellement, il est possible de passer un attribut "label".

    Voici un exemple :

    C_OBJECT($ob)
    OB SET($ob;"valueType";"event")
    OB SET($ob;"label";"Edit...")

    Gestion des événements

    Plusieurs événements peuvent être gérés lors de l'utilisation d'une listbox tableau d'objets :

    • On Data Change: An On Data Change event is triggered when any value has been modified either:
      • zone de saisie de texte
      • listes déroulante
      • zone de combo box
      • bouton d'unité (passage valeur x à valeur x+1)
      • case à cocher (passage cochée/non cochée)
    • On Clicked: When the user clicks on a button installed using the "event" valueType attribute, an On Clicked event will be generated. Cet événement doit être ensuite géré par le programmeur.
    • On Alternative Click: When the user clicks on an ellipsis button ("alternateButton" attribute), an On Alternative Click event will be generated. Cet événement doit être ensuite géré par le programmeur.