<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<!-- THIS FILE IS GENERATED DO NOT EDIT -->


<erlref>
<header>
  <copyright>
    <year>2020</year>
    <holder>Ericsson AB. All Rights Reserved.</holder></copyright>
  <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

  </legalnotice>
  <title>wxButton</title>
</header>
<module>wxButton</module>
<modulesummary>Functions for wxButton class</modulesummary>
<description><p>A button is a control that contains a text string, and is one of the most common elements of a GUI.
      </p><p>It may be placed on a <seeerl marker="wxDialog"><c>wxDialog</c></seeerl> or on a <seeerl marker="wxPanel"><c>wxPanel</c></seeerl> panel, or indeed on almost any other window.
      </p><p>By default, i.e. if none of the alignment styles are specified, the label is centered both horizontally and vertically. If the button has both a label and a bitmap, the alignment styles above specify the location of the rectangle combining both the label and the bitmap and the bitmap position set with <c>wxButton::SetBitmapPosition()</c> (not implemented in wx) defines the relative position of the bitmap with respect to the label (however currently non-default alignment combinations are not implemented on all platforms).
      </p><p>Since version 2.9.1 <seeerl marker="wxButton"><c>wxButton</c></seeerl> supports showing both text and an image (currently only when using wxMSW, wxGTK or wxOSX/Cocoa ports), see <c>SetBitmap()</c> (not implemented in wx) and <seemfa marker="#setBitmapLabel/2"><c>setBitmapLabel/2</c></seemfa>, <seemfa marker="#setBitmapDisabled/2"><c>setBitmapDisabled/2</c></seemfa> &amp;c methods. In the previous wxWidgets versions this functionality was only available in (the now trivial) <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl> class which was only capable of showing an image without text.
      </p><p>A button may have either a single image for all states or different images for the following states (different images are not currently supported under macOS where the normal image is used for all states): 
      </p><p> All of the bitmaps must be of the same size and the normal bitmap must be set first (to a valid bitmap), before setting any other ones. Also, if the size of the bitmaps is changed later, you need to change the size of the normal bitmap before setting any other bitmaps with the new size (and you do need to reset all of them as their original values can be lost when the normal bitmap size changes).
      </p><p>The position of the image inside the button be configured using <c>SetBitmapPosition()</c> (not implemented in wx). By default the image is on the left of the text.
      </p><p>Please also notice that GTK+ uses a global setting called <c>gtk-button-images</c> to determine if the images should be shown in the buttons at all. If it is off (which is the case in e.g. Gnome 2.28 by default), no images will be shown, consistently with the native behaviour.
      </p><p>Styles</p><p>This class supports the following styles:
      </p><p>See: <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl>
      </p>
  <p>This class is derived (and can use functions) from: 
    <seeerl marker="wxControl"><c>wxControl</c></seeerl> <seeerl marker="wxWindow"><c>wxWindow</c></seeerl> <seeerl marker="wxEvtHandler"><c>wxEvtHandler</c></seeerl></p>
  
  <p>wxWidgets docs: <url href="https://docs.wxwidgets.org/3.1/classwx_button.html">wxButton</url></p>
  </description><section><title>Events</title><p>Event types emitted from this class: <seeerl marker="wxCommandEvent"><c>command_button_clicked</c></seeerl></p></section>
<datatypes><datatype><name name="wxButton"/></datatype></datatypes>

<funcs>
  <func>
    <name name="new" arity="0" clause_i="1" since=""/>
    <fsummary>Default ctor. </fsummary>
    <desc><p>Default ctor. 
      </p></desc>
  </func>
  
  <func>
    <name name="new" arity="2" clause_i="1" since=""/>
    <fsummary>See: <c>new/3</c></fsummary>
  </func>
  
  <func>
    <name name="new" arity="3" clause_i="1" since=""/>
    <fsummary>Constructor, creating and showing a button. </fsummary>
    <desc><p>Constructor, creating and showing a button. 
      </p><p>The preferred way to create standard buttons is to use default value of <c>label</c>. If no label is supplied and <c>id</c> is one of standard IDs from this list, a standard label will be used. In other words, if you use a predefined <c>wxID_XXX</c> constant, just omit the label completely rather than specifying it. In particular, help buttons (the ones with <c>id</c> of <c>wxID_HELP</c>) under macOS can't display any label at all and while <seeerl marker="wxButton"><c>wxButton</c></seeerl> will detect if the standard "Help" label is used and ignore it, using any other label will prevent the button from correctly appearing as a help button and so should be avoided.
      </p><p>In addition to that, the button will be decorated with stock icons under GTK+ 2.
      </p><p>See: <seemfa marker="#create/4"><c>create/4</c></seemfa>, <c>wxValidator</c> (not implemented in wx)
      </p></desc>
  </func>
  
  <func>
    <name name="create" arity="3" clause_i="1" since=""/>
    <fsummary>See: <c>create/4</c></fsummary>
  </func>
  
  <func>
    <name name="create" arity="4" clause_i="1" since=""/>
    <fsummary>Button creation function for two-step creation. </fsummary>
    <desc><p>Button creation function for two-step creation. 
      </p><p>For more details, see <seemfa marker="#new/3"><c>new/3</c></seemfa>. 
      </p></desc>
  </func>
  
  <func>
    <name name="getDefaultSize" arity="0" clause_i="1" since=""/>
    <fsummary>Returns the default size for the buttons. </fsummary>
    <desc><p>Returns the default size for the buttons. 
      </p><p>It is advised to make all the dialog buttons of the same size and this function allows retrieving the (platform, and current font dependent) size which should be the best suited for this.
      </p><p>The optional <c>win</c> argument is new since wxWidgets 3.1.3 and allows to get a per-monitor DPI specific size. 
      </p></desc>
  </func>
  
  <func>
    <name name="getDefaultSize" arity="1" clause_i="1" since=""/>
    <fsummary/>
    <desc/>
  </func>
  
  <func>
    <name name="setDefault" arity="1" clause_i="1" since=""/>
    <fsummary>This sets the button to be the default item in its top-level window (e.g. </fsummary>
    <desc><p>This sets the button to be the default item in its top-level window (e.g. 
      </p><p>the panel or the dialog box containing it).
      </p><p>As normal, pressing return causes the default button to be depressed when the return key is pressed.
      </p><p>See also <seemfa marker="wxWindow#setFocus/1"><c>wxWindow:setFocus/1</c></seemfa> which sets the keyboard focus for windows and text panel items, and <c>wxTopLevelWindow::SetDefaultItem()</c> (not implemented in wx).
      </p><p>Remark: Under Windows, only dialog box buttons respond to this function.
      </p><p>Return: the old default item (possibly NULL) 
      </p></desc>
  </func>
  
  <func>
    <name name="setLabel" arity="2" clause_i="1" since=""/>
    <fsummary>Sets the string label for the button. </fsummary>
    <desc><p>Sets the string label for the button. 
      </p></desc>
  </func>
  
  <func>
    <name name="getBitmapDisabled" arity="1" clause_i="1" since=""/>
    <fsummary>Returns the bitmap for the disabled state, which may be invalid. </fsummary>
    <desc><p>Returns the bitmap for the disabled state, which may be invalid. 
      </p><p>See: <seemfa marker="#setBitmapDisabled/2"><c>setBitmapDisabled/2</c></seemfa>
      </p><p>Since: 2.9.1 (available in <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl> only in previous versions) 
      </p></desc>
  </func>
  
  <func>
    <name name="getBitmapFocus" arity="1" clause_i="1" since=""/>
    <fsummary>Returns the bitmap for the focused state, which may be invalid. </fsummary>
    <desc><p>Returns the bitmap for the focused state, which may be invalid. 
      </p><p>See: <seemfa marker="#setBitmapFocus/2"><c>setBitmapFocus/2</c></seemfa>
      </p><p>Since: 2.9.1 (available in <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl> only in previous versions) 
      </p></desc>
  </func>
  
  <func>
    <name name="getBitmapLabel" arity="1" clause_i="1" since=""/>
    <fsummary>Returns the bitmap for the normal state. </fsummary>
    <desc><p>Returns the bitmap for the normal state. 
      </p><p>This is exactly the same as <c>GetBitmap()</c> (not implemented in wx) but uses a name backwards-compatible with <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl>.
      </p><p>See: <c>SetBitmap()</c> (not implemented in wx), <seemfa marker="#setBitmapLabel/2"><c>setBitmapLabel/2</c></seemfa>
      </p><p>Since: 2.9.1 (available in <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl> only in previous versions) 
      </p></desc>
  </func>
  
  <func>
    <name name="setBitmapDisabled" arity="2" clause_i="1" since=""/>
    <fsummary>Sets the bitmap for the disabled button appearance. </fsummary>
    <desc><p>Sets the bitmap for the disabled button appearance. 
      </p><p>If <c>bitmap</c> is invalid, the disabled bitmap is set to the automatically generated greyed out version of the normal bitmap, i.e. the same bitmap as is used by default if this method is not called at all. Use <c>SetBitmap()</c> (not implemented in wx) with an invalid bitmap to remove the bitmap completely (for all states).
      </p><p>See: <seemfa marker="#getBitmapDisabled/1"><c>getBitmapDisabled/1</c></seemfa>, <seemfa marker="#setBitmapLabel/2"><c>setBitmapLabel/2</c></seemfa>, <c>SetBitmapPressed()</c> (not implemented in wx), <seemfa marker="#setBitmapFocus/2"><c>setBitmapFocus/2</c></seemfa>
      </p><p>Since: 2.9.1 (available in <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl> only in previous versions) 
      </p></desc>
  </func>
  
  <func>
    <name name="setBitmapFocus" arity="2" clause_i="1" since=""/>
    <fsummary>Sets the bitmap for the button appearance when it has the keyboard focus. </fsummary>
    <desc><p>Sets the bitmap for the button appearance when it has the keyboard focus. 
      </p><p>If <c>bitmap</c> is invalid, the normal bitmap will be used in the focused state.
      </p><p>See: <seemfa marker="#getBitmapFocus/1"><c>getBitmapFocus/1</c></seemfa>, <seemfa marker="#setBitmapLabel/2"><c>setBitmapLabel/2</c></seemfa>, <c>SetBitmapPressed()</c> (not implemented in wx), <seemfa marker="#setBitmapDisabled/2"><c>setBitmapDisabled/2</c></seemfa>
      </p><p>Since: 2.9.1 (available in <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl> only in previous versions) 
      </p></desc>
  </func>
  
  <func>
    <name name="setBitmapLabel" arity="2" clause_i="1" since=""/>
    <fsummary>Sets the bitmap label for the button. </fsummary>
    <desc><p>Sets the bitmap label for the button. 
      </p><p>Remark: This is the bitmap used for the unselected state, and for all other states if no other bitmaps are provided.
      </p><p>See: <c>SetBitmap()</c> (not implemented in wx), <seemfa marker="#getBitmapLabel/1"><c>getBitmapLabel/1</c></seemfa>
      </p><p>Since: 2.9.1 (available in <seeerl marker="wxBitmapButton"><c>wxBitmapButton</c></seeerl> only in previous versions) 
      </p></desc>
  </func>
  
  <func>
    <name name="destroy" arity="1" clause_i="1" since=""/>
    <fsummary>Destructor</fsummary>
    <desc><p>Destroys the object.</p></desc>
  </func>
  </funcs>
</erlref>
