DialogHost

De Wiki Pokémon SDK
Aller à : navigation, rechercher

Introduction

DialogHost est une classe de l'outil RubyHost, cette classe vous permet de définir simplement le comportement d'une interface DialogBox contenue dans Ruby Host.exe. Cette classe a pour but de rendre l'édition des données de PSDK et de ses interface d'édition plus agréable.

Variables d'instance

@locked (gérée en interne)
Indique si l'interface est verrouillée pour traitement et empêche donc tous les messages arrivants d'agir d'une quelconque manière sur le processus de traitement coté Ruby.
@object
Contient l'objet qui est actuellement modifié par l'interface. Ses variables d'instance seront modifiés à chaque mise à jour des données.
@hwnd
Contient la valeur numérique du HWND (identifiant) de la DialogBox.
@dlg
Contient l'objet DialogObject qui permet l'action à la couche de niveau inférieur sur la DialogBox (interface Ruby <-> C++)
@combos
Contient l'ensemble des ComboBox et ListBox ayant une méthode de traitement lors de leur changement. (N'influençant donc pas sur les données.)
@buttons
Contient l'ensemble des Button.
@fields
Contient l'ensemble des champs ayant une action directe sur les éléments de l'objet contenu dans *@object*.
@spins
Contient l'ensemble des Spin Boxes. (Cette variable contient souvent rien, pensez à la vérifier avant d'y accéder).

Méthodes Noyau

Ces méthodes servent au fonctionnement natif de DialogHost, elles définissent le comportement de DialogHost vis à vis de la DialogBox qui sera ouverte.

Initialisation

initialize(dialog_id, parent_hwnd = 0)
Fonction d'initialisation de l'objet DialogHost, cette méthode va charger et afficher la DialogBox d'id interne dialog_id. Les données seront affiché suite à l'invocation de la méthode init_data (vous servant de point d'entrée pour définir les différents composant de votre interface).
Cette méthode peut prendre un bloc en paramètre, il a pour argument l'objet lui même, ceci vous permet de gérer les fenêtres déjà ouvertes.

Exemple :

  def Item_Dialog.instanciate
    if @instance and !@instance.closed?
      return @instance.set_forground
    end
    Item_Dialog.new(App::Dialogs[:objets], 0) { |instance| @instance = instance}
  end
init_dialog(dialog)
Fonction permettant de définir le comportement de base de la DialogBox en fonction des messages qu'il reçoit.
init_data(dialog)
Fonction permettant de définir l'intégralité des éléments d'interface de la DialogBox puis, de manière interne, d'initialiser les liste des ComboBox et ListBox.
Lorsque vous définissez cette méthode dans une classe dérivée, vous devez impérativement appeler super. Si vous faites autrement, il est possible que certains champs soient mal initialisés à l'ouverture de la DialogBox.

Exemple :

  def init_data(dialog)
    define_unsigned_int(1, :@price, 0, 9_000_000)
    define_button(1, :_save)
    super
  end

Test de fermeture et affichage

Deux méthodes primordiales qui peuvent vous servir lors de la programmation de votre interface.

closed?
Vous indique si la DialogBox est fermée. Dans ce cas, l'interface n'est plus opérante et vous ne devez plus rien faire de cet objet.
set_forground
Dans le cas contraire, vous pouvez appeler cette méthode pour afficher la DialogBox au premier plan (lorsqu'elle n'a pas d'enfant).

Action induite par les messages

combo_list_sel_change(id)
Méthode appelée lorsqu'un évènement relatif à un changement de sélection d'une ListBox ou ComboBox est constaté.
Cette méthode appellera la méthode ":on_change_method" avec l'argument index et text qui correspondent respectivement à l'index de la selection de la ComboBox/ListBox et du texte qui y est associé. Si la méthode ":on_change_method" renvoie :update_dialog l'ensemble des champs sont mis à jour.
button_press(id)
Méthode invoquant la méthode de traitement associé au bouton concerné.
Met à jour les champs si le retour de la méthode de traitement associé renvoie :update_dialog.
spin_notify(id, lParam)
Méthode invoquant la méthode ":on_change_method" avec l'argument delta (qui correspond à la valeur à ajouter à un index).
Met à jour les champs si le retour de la méthode ":on_change_method" renvoie :update_dialog.

Méthode de définition

Ensemble de méthode définissant des champs ou des éléments d'action de la DialogBox. Ceci vous mâchera la plupart du travail pour peu que vous définissiez quelques méthodes supplémentaires.

Toutes les méthodes prenne un argument index, cet argument correspond à l'index à utiliser dans les listes App::Button, App::Images, App::Edit, App::Combo, App::Radio, App::Check, App::Spin et App::List pour retrouver l'id du champ concerné.

define_spin_controler(index, on_change)
Définie une Spin Box déclenchant la méthode ":on_change_method" nommé par le symbole contenu dans on_change.
La méthode pointé par on_change doit avoir l'argument delta.
define_list_controler(index, on_change, list_data, initial_index = 0)
Définit une ListBox de contrôle qui déclenche une méthode ":on_change_method" nommé par le symbole contenu dans on_change.
list_data peut être la liste des différents texte comme symbole correspondant au nom de la méthode qui renvoie cette liste.
initial_index correspond à l'index de la ListBox lorsque la DialogBox est ouverte.
define_combo_controler(index, on_change, list_data, initial_index = 0)
Même chose que *define_list_controler* mais pour les ComboBox

Exemple :

  def init_data(dialog)
    # <...>
    define_combo_controler(1, :_on_item_change, :_item_list)
    # <...>
    super
  end

  def _on_item_change(index, text)
    id = text.split(TEXT_SPLIT).last.to_i
    id = 1 if(id < 1 or id >= $game_data_item.size)
    check_update_data
    @object = $game_data_item[id]
    @item_id = id
    return :update_dialog
  end
  
  def _item_list
    if @item_list and (@item_list.size + 1) == $game_data_item.size
      return @item_list
    else
      lang = @lang_id
      @item_list = Array.new($game_data_item.size - 1) do |i| 
        sprintf(TEXT_FORMAT, GameData::Text._get(lang, 12, i+1), i+1)
      end
    end
    return @item_list
  end
define_list(index, list_data, getter, setter)
Définit une liste passive qui correspond à une valeur de l'objet modifié par l'interface.
list_data est défini de la même manière.
getter et setter sont les symboles des méthodes qui seront appelés pour récupérer et modifier les données. La méthode setter a les même arguments que ":on_change_method".
define_combo(index, list_data, getter, setter)
Même chose que *define_list* mais pour une ComboBox.
define_button(index, callback)
Définit un bouton qui appellera la méthode pointé par callback (symbole) lorsque celui-ci sera cliqué.
define_image(index, loader, selector = nil)
Définit une image affiché dans l'interface.
loader est le symbole de la méthode qui renvoie le nom de fichier de l'image.
selector définit la fonction appelée lorsqu'un clic sera fait sur l'image.

Exemple :

  def init_data(dialog)
    # <...>
    define_image(1, :_icon_filename, :_change_icon)
    # <...>
    super
  end

  def _icon_filename
    get_file_name("#{ICON_PATH}#{@object.icon}#{ICON_EXT}")
  end
  
  def _change_icon
    filename = open_file_dialog(EXT_DESCR, ICON_EXT, ICON_PATH)
    if(filename)
      check_update_data
      @object.icon = filename
      @last_time -= 2
      return :update_dialog
    end
  end
define_text_view(index, getter)
Défini un champ de texte qui ne sert qu'à afficher des données et qui n'agit pas sur l'objet.
getter est le symbole de la méthode qui renvoie le contenu de ce champ.
define_text_control(index, instance_variable, text_size, text_check_sym = nil)
Définit un champ de texte qui agit sur l'objet.
instance_variable est le symbole de la variable d'instance de l'objet modifié. (Ou un hash définissant un setter et getter avec les clés :getter et :setter).
text_size correspond à la longueur maximale que votre champ doit respecter.
text_check_sym est le symbole de la méthode qui corrige le texte en cas de soucis ou qui permet de le convertir en quelque chose de compatible avec la variable d'instance. (Optionnel)
define_signed_int(index, instance_variable, min, max)
Définit un champ de texte de type Nombre relatif.
min et max sont les bornes dans lequel le nombre doit être contenu.
define_unsigned_int(index, instance_variable, min, max)
Même chose mais avec un nombre naturel.
define_checkbox(index, instance_variable)
Défini une CheckBox qui définira un état true/false de la variable d'instance.
get_list_data_var(list_data)
Méthode utilisée par define_list_controler, define_combo_controler, define_list et define_combo. (Traitement de l'argument list_data).

Méthode de mise à jour

Méthodes de mise à jour des champs ou des données de l'objet.

Méthodes principales

update_dialog
Mise à jour des champs de la DialogBox.
update_data
Mise à jour (forcée) des données de l'objet modifié.
update_combo(index, position, update_dlg = false, update_list = true)
Mise à jour de la position d'une ComboBox avec éventuellement une mise à jour du dialog (update_dlg) et une mise à jour de la liste des options (update_list).
update_list(index, position, update_dlg = false, update_list = true)
Même chose avec les ListBox.
update_text(index, text)
Mise à jour du texte contenu dans un champ de texte.
update_signed_int(index, value)
Mise à jour du nombre signé dans un champ de texte.
update_unsigned_int(index, value)
Mise à jour du nombre positif dans un champ de texte.

Méthodes utilisés pendant le processus de mise à jour

ivar_get(ivar)
Permet de récupérer la valeur d'une variable d'instance de l'objet (ou d'appeler un getter).
ivar_set(ivar, value)
Permet de modifier la valeur d'une variable d'instance de l'objet (ou d'appeler un setter).
normalize_value(value, field)
Permet repositionner une valeur dans un intervalle [min, max] défini dans field.
load_image(dlg, id, field)
Permet de charger une image dans un champ de la DialogBox.

Méthodes utilitaires

Un ensemble de méthodes vous permettant de programmer plus facilement vos interfaces.

get_file_name(filename)
Renvoie le nom de fichier relativement au projet ouvert.
open_file_dialog(ext_descr, ext_name, force_dir = nil)
Permet de choisir un fichier d'une extension définie dans *ext_name* et d'éventuellement forcer la présence de ce fichier dans un dossier du jeu à l'aide de *force_dir*. Le paramètre ext_descr vous permet simplement d'indiquer explicitement à quoi correspond l'extension.
msgbox(text, title, flag = DialogInterface
:Constants::MB_ICONASTERISK)
Affiche une boite de dialogue avec pour titre *title* et contenu *text*. Vous pouvez personnaliser la boite de dialogue en utilisant une combinaison de constant DialogInterface::Constants::MB_*.
confirm(text, title)
Affiche une boite de dialogue oui / non à l'utilisateur. Les arguments sont similaires à msgbox à la différence qu'aucun flag ne peut-être utilisé. Cette méthode renvoie true si l'utilisateur a appuyé sur Oui, false sinon.
check_update_data
Fonction à utiliser si vous souhaitez que les données soient sauvegardés selon certaines règles. Vous devez utiliser cette méthode à la place de update_data.
check_text_before_adding(max, lang_id, *texts)
Vous permet de vérifier si vous avez assez de texte pour créer un nouvel objet dans la base de données. L'argument max correspond à l'id de l'objet que vous désirez ajouter. Les valeurs contenues dans texts sont les ids des fichier texte dans lesquels vérifier s'il y a assez de texte.
Cette fonction renvoie true s'il y a assez de texte.
get_edit_value(index, type = :text)
Cette fonction vous permet de récupérer la valeur d'un champ EditBox en fonction de son type de données (:text, :signed et :unsigned).