.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.FileDialogCustomizeHook:

==========================================================================================================================================
|phoenix_title|  **wx.FileDialogCustomizeHook**
==========================================================================================================================================

Base class for customization hooks used with :ref:`wx.FileDialog`.          

:ref:`wx.FileDialogCustomizeHook`  is an abstract base class, i.e. in order to use a concrete class inheriting from it and implementing its pure virtual :meth:`~wx.FileDialogCustomizeHook.AddCustomControls`  function must be defined. Then an object of this class should be passed to :meth:`wx.FileDialog.SetCustomizeHook` , which will result in its :meth:`~wx.FileDialogCustomizeHook.AddCustomControls`  being called before the dialog is shown, :meth:`~wx.FileDialogCustomizeHook.UpdateCustomControls`  being called whenever something changes in the dialog while it is shown and, finally, :meth:`~wx.FileDialogCustomizeHook.TransferDataFromCustomControls`  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: ::

    class EncryptHook(wx.FileDialogCustomizeHook):

        def __init__(self):
            super().__init__()
            self.encrypt = False

        # Override to add custom controls using the provided customizer object.
        def AddCustomControls(self, customizer):

            # Suppose we can encrypt files when saving them.
            self.checkbox = customizer.AddCheckBox("Encrypt")

            # While self.checkbox is not really a wx.CheckBox, it looks almost like one
            # and, in particular, we can bind to custom control events as usual.
            self.checkbox.Bind(wx.EVT_CHECKBOX, self.OnCheckbox)

            # The encryption parameters can be edited in a dedicated dialog.
            self.button = customizer.AddButton("Parameters...")
            self.button.Bind(wx.EVT_BUTTON, self.OnButton)

        def OnCheckbox(self, event):
            self.button.Enable(event.IsChecked())

        def OnButton(self, event):
            ... show the encryption parameters dialog here ...


        # Override this to save the values of the custom controls.
        def TransferDataFromCustomControls(self):
            # Save the checkbox value, as we won't be able to use it any more
            # once this function returns.
            self.encrypt = self.checkbox.GetValue()

    ...

    def SomeOtherEventHandlerFunc(self, event):

        dialog = wx.FileDialog(None, "Save document", "", "file.my",
                    "My files (*.my)|*.my", wx.FD_SAVE | wx.FD_OVERWRITE_PROMPT)

        # This object may be destroyed before the dialog, but must remain alive
        # until ShowModal() returns. So you should hold a separate reference to
        # it.
        customizeHook = EncryptHook()
        dialog.SetCustomizeHook(customizeHook)

        if dialog.ShowModal() == wx.ID_OK:
            if (customizeHook.encrypt)
                ... save with encryption ...
            else:
                ... save without encryption ...

        dialog.Destroy()







         



.. versionadded:: 4.1/wxWidgets-3.1.7  
     







.. seealso:: :ref:`wx.FileDialog`  







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>FileDialogCustomizeHook</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.FileDialogCustomizeHook_inheritance.png" alt="Inheritance diagram of FileDialogCustomizeHook" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.FileDialogCustomizeHook.html" title="Base class for customization hooks used with wx.FileDialog." alt="" coords="5,5,209,35"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.FileDialogCustomizeHook.AddCustomControls`                            Must be overridden to add custom controls to the dialog using the provided customizer object.
:meth:`~wx.FileDialogCustomizeHook.TransferDataFromCustomControls`               Should typically be overridden to save the values of the custom controls when the dialog is accepted.
:meth:`~wx.FileDialogCustomizeHook.UpdateCustomControls`                         May be overridden to update the custom controls whenever something changes in the dialog.
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.FileDialogCustomizeHook(object)

   Base class for customization hooks used with FileDialog.



   .. method:: AddCustomControls(self, customizer)

      Must be overridden to add custom controls to the dialog using the provided customizer object.                  

      Call :ref:`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`: 
      :type `customizer`: wx.FileDialogCustomize







   .. method:: TransferDataFromCustomControls(self)

      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 :meth:`wx.FileDialog.ShowModal`   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.                   





   .. method:: UpdateCustomControls(self)

      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.