# :stopdoc:
# This file is automatically generated by the WXRuby3 documentation 
# generator. Do not alter this file.
# :startdoc:


module Wx

  # Base class for customization hooks used with {Wx::FileDialog}.
  # 
  # {Wx::FileDialogCustomizeHook} is an abstract base class, i.e. in order to use a concrete class inheriting from it and implementing its pure virtual {Wx::FileDialogCustomizeHook#add_custom_controls} function must be defined. Then an object of this class should be passed to {Wx::FileDialog#set_customize_hook}, which will result in its {Wx::FileDialogCustomizeHook#add_custom_controls} being called before the dialog is shown, {Wx::FileDialogCustomizeHook#update_custom_controls} being called whenever something changes in the dialog while it is shown and, finally, {Wx::FileDialogCustomizeHook#transfer_data_from_custom_controls} being called when the user accepts their choice in the dialog.
  # Putting all this together, here is an example of customizing the file dialog using this class: 
  # ```ruby
  # class EncryptHook < Wx::FileDialogCustomizeHook
  # 
  #   attr_reader :encrypt
  # 
  #   # Override to add custom controls using the provided customizer object.
  #   def add_custom_controls(customizer)
  #     # Suppose we can encrypt files when saving them.
  #     @checkbox = customizer.add_check_box('Encrypt')
  # 
  #     # While @checkbox is not a Wx::CheckBox, it looks almost like one
  #     # and, in particular, we can bind to custom control events as usual.
  #     @checkbox.evt_checkbox(Wx::ID_ANY) do |event| 
  #        # We can also call Wx::Window-like functions on them.
  #        @button.enable(event.checked?)
  #     end
  # 
  #     # The encryption parameters can be edited in a dedicated dialog.
  #     @button = customizer.add_button('Parameters...')
  #     @button.evt_button(Wx::ID_ANY) do |event|
  #        # ... show the encryption parameters dialog here ...
  #     end
  #   end
  # 
  #   # Override to save the values of the custom controls.
  #   def transfer_data_from_custom_controls 
  #     # Save the checkbox value, as we won't be able to use it any more
  #     # once this function returns.
  #     @encrypt = @checkbox.get_value
  #   end
  # 
  # end
  # 
  # # ...
  # 
  # def some_method
  #   Wx.FileDialog(nil, 'Save document', '', 'file.my',
  #                      'My files (*.my)|*.my',
  #                      Wx::FD_SAVE | Wx::FD_OVERWRITE_PROMPT) do |dialog|
  # 
  #     # This object may be destroyed before the dialog, but must remain
  #     # alive until #show_modal returns.
  #     customize_hook = EncryptHook.new
  #     dialog.set_customize_hook(custom_hook)
  # 
  #     if dialog.show_modal == Wx::ID_OK 
  #       if customize_hook.encrypt 
  #         # ... save with encryption ...
  #       else
  #         # ... save without encryption ...
  #       end
  #     end
  # end
  # ```
  # 
  # Category:  Common Dialogs
  # @see Wx::FileDialog
  # 
  # 
  # @wxrb_require USE_FILEDLG
  class FileDialogCustomizeHook < ::Object
  
    # Must be overridden to add custom controls to the dialog using the provided customizer object.
    # 
    # Call {Wx::FileDialogCustomize} functions to add controls and possibly bind to their events.
    # Note that there is no possibility to define the custom controls layout, they will appear more or less consecutively, but the exact layout is determined by the current platform.
    # @param customizer [Wx::FileDialogCustomize] 
    # @return [void]
    def add_custom_controls(customizer) end
    
    # May be overridden to update the custom controls whenever something changes in the dialog.
    # 
    # This function is called when the user selects a file, changes the directory or changes the current filter in the dialog, for example. It can be used to update the custom controls state depending on the currently selected file, for example.
    # Note that it is not necessarily called when the value of a custom control changes.
    # Base class version does nothing.
    # @return [void]
    def update_custom_controls; end
    
    # Should typically be overridden to save the values of the custom controls when the dialog is accepted.
    # 
    # Custom controls are destroyed and cannot be used any longer once {Wx::FileDialog#show_modal} returns, so their values must be retrieved in this function, which is called just before this happens.
    # This function is not called if the user cancels the dialog.
    # Base class version does nothing.
    # @return [void]
    def transfer_data_from_custom_controls; end
    
  end # FileDialogCustomizeHook
  
  # Used with {Wx::FileDialogCustomizeHook} to add custom controls to {Wx::FileDialog}.
  # 
  # An object of this class is passed to {Wx::FileDialogCustomizeHook#add_custom_controls} to allow it to actually add controls to the dialog.
  # The pointers returned by the functions of this class belong to wxWidgets and should not be deleted by the application, just as {Wx::Window}-derived objects (even if these controls do not inherit from {Wx::Window}). These pointers become invalid when {Wx::FileDialog#show_modal} returns, and the dialog containing them is destroyed, and the latest point at which they can be still used is when {Wx::FileDialogCustomizeHook#transfer_data_from_custom_controls} is called.
  # 
  # Category:  Common Dialogs
  # @see Wx::FileDialog
  # 
  # 
  # 
  # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
  # @wxrb_require USE_FILEDLG
  class FileDialogCustomize < ::Object
  
    # Add a button with the specified label.
    # @param label [String] 
    # @return [Wx::FileDialogButton]
    def add_button(label) end
    
    # Add a checkbox with the specified label.
    # @param label [String] 
    # @return [Wx::FileDialogCheckBox]
    def add_check_box(label) end
    
    # Add a radio button with the specified label.
    # 
    # The first radio button added will be initially checked. All the radio buttons added immediately after it will become part of the same radio group and will not be checked, but checking any one of them later will uncheck the first button and all the other ones.
    # If two consecutive but distinct radio groups are required, {Wx::FileDialogCustomize#add_static_text} with an empty label can be used to separate them.
    # @param label [String] 
    # @return [Wx::FileDialogRadioButton]
    def add_radio_button(label) end
    
    # Add a read-only combobox with the specified contents.
    # 
    # The combobox doesn't have any initial selection, i.e. {Wx::FileDialogChoice#get_selection} returns {Wx::NOT_FOUND}, if some item must be selected, use {Wx::FileDialogChoice#set_selection} explicitly to do it.
    # @param n [Integer]  The number of strings, must be positive, as there is no way to add more strings later and creating an empty combobox is not very useful.
    # @param strings [String]  A non-NULL pointer to an array of n strings.
    # @return [Wx::FileDialogChoice]
    def add_choice(n, strings) end
    
    # Add a text control with an optional label preceding it.
    # 
    # Unlike all the other functions for adding controls, the label parameter here doesn't specify the contents of the text control itself, but rather the label appearing before it. Unlike static controls added by {Wx::FileDialogCustomize#add_static_text}, this label is guaranteed to be immediately adjacent to it.
    # If label is empty, no label is created.
    # @param label [String] 
    # @return [Wx::FileDialogTextCtrl]
    def add_text_ctrl(label=(())) end
    
    # Add a static text with the given contents.
    # 
    # The contents of the static text can be updated later, i.e. it doesn't need to be actually static.
    # @param label [String] 
    # @return [Wx::FileDialogStaticText]
    def add_static_text(label) end
    
  end # FileDialogCustomize
  

end