added vendor display name (for consistency with app display name &c) (patch 1831303)

[wxWidgets.git] / docs / latex / wx / comboctrl.tex

diff --git a/docs/latex/wx/comboctrl.tex b/docs/latex/wx/comboctrl.tex
index f7b7921cfbed01d2be7dde419ca730731e1a678b..1798986e0e974b53c7d3a460cc38eed08cf4b4ef 100644 (file)
--- a/docs/latex/wx/comboctrl.tex
+++ b/docs/latex/wx/comboctrl.tex
@@ -36,6 +36,10 @@ Here's a minimal sample of \helpref{wxListView}{wxlistview} popup:
 
 #include <wx/combo.h>
 #include <wx/listctrl.h>
 
 #include <wx/combo.h>
 #include <wx/listctrl.h>

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 
 class wxListViewComboPopup : public wxListView,
                              public wxComboPopup
 
 class wxListViewComboPopup : public wxListView,
                              public wxComboPopup


@@ -130,14 +134,14 @@ Here's how you would create and populate it in a dialog constructor:
 
 \wxheading{Include files}
 
 
 \wxheading{Include files}
 

-<combo.h>
+<wx/combo.h>

 
 \wxheading{Window styles}
 
 \begin{twocollist}\itemsep=0pt
 \twocolitem{\windowstyle{wxCB\_READONLY}}{Text will not be editable.}
 \twocolitem{\windowstyle{wxCB\_SORT}}{Sorts the entries in the list alphabetically.}
 
 \wxheading{Window styles}
 
 \begin{twocollist}\itemsep=0pt
 \twocolitem{\windowstyle{wxCB\_READONLY}}{Text will not be editable.}
 \twocolitem{\windowstyle{wxCB\_SORT}}{Sorts the entries in the list alphabetically.}

-\twocolitem{\windowstyle{wxPROCESS\_ENTER}}{The control will generate
+\twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate

 the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key
 is either processed internally by the control or used for navigation between
 dialog controls). Windows only.}
 the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key
 is either processed internally by the control or used for navigation between
 dialog controls). Windows only.}


@@ -145,9 +149,6 @@ dialog controls). Windows only.}
 to popup's OnComboDoubleClick. Actual behaviour is defined by a derived
 class. For instance, wxOwnerDrawnComboBox will cycle an item. This style only
 applies if wxCB\_READONLY is used as well.}
 to popup's OnComboDoubleClick. Actual behaviour is defined by a derived
 class. For instance, wxOwnerDrawnComboBox will cycle an item. This style only
 applies if wxCB\_READONLY is used as well.}

-\twocolitem{\windowstyle{wxCC\_ALT\_KEYS}}{Use keyboard behaviour alternate
-to platform default: up and down keys will show popup (instead of cycling value,
-for instance, on wxMSW).}

 \twocolitem{\windowstyle{wxCC\_STD\_BUTTON}}{Drop button will behave
 more like a standard push button.}
 \end{twocollist}
 \twocolitem{\windowstyle{wxCC\_STD\_BUTTON}}{Drop button will behave
 more like a standard push button.}
 \end{twocollist}


@@ -216,6 +217,25 @@ appropriately.}
 Destructor, destroying the combo control.
 
 
 Destructor, destroying the combo control.
 
 

+\membersection{wxComboCtrl::AnimateShow}\label{wxcomboctrlanimateshow}
+
+\func{virtual bool}{AnimateShow}{\param{const wxRect\& }{rect}, \param{int }{flags}}
+
+This member function is not normally called in application code.
+Instead, it can be implemented in a derived class to create a
+custom popup animation.
+
+\wxheading{Parameters}
+
+Same as in \helpref{DoShowPopup}{wxcomboctrldoshowpopup}.
+
+\wxheading{Return value}
+
+\true if animation finishes before the function returns.
+\false otherwise. In the latter case you need to manually call DoShowPopup
+after the animation ends.
+
+

 \membersection{wxComboCtrl::Create}\label{wxcomboctrlcreate}
 
 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 \membersection{wxComboCtrl::Create}\label{wxcomboctrlcreate}
 
 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp


@@ -241,6 +261,52 @@ Copies the selected text to the clipboard.
 Copies the selected text to the clipboard and removes the selection.
 
 
 Copies the selected text to the clipboard and removes the selection.
 
 

+\membersection{wxComboCtrl::DoSetPopupControl}\label{wxcomboctrldosetpopupcontrol}
+
+\func{void}{DoSetPopupControl}{\param{wxComboPopup* }{popup}}
+
+This member function is not normally called in application code.
+Instead, it can be implemented in a derived class to return
+default wxComboPopup, incase {\tt popup} is NULL.
+
+\textbf{Note:} If you have implemented OnButtonClick to do
+something else than show the popup, then DoSetPopupControl
+must always return NULL.
+
+
+\membersection{wxComboCtrl::DoShowPopup}\label{wxcomboctrldoshowpopup}
+
+\func{virtual void}{DoShowPopup}{\param{const wxRect\& }{rect}, \param{int }{flags}}
+
+This member function is not normally called in application code.
+Instead, it must be called in a derived class to make sure popup
+is properly shown after a popup animation has finished (but only
+if \helpref{AnimateShow}{wxcomboctrlanimateshow} did not finish
+the animation within it's function scope).
+
+\wxheading{Parameters}
+
+\docparam{rect}{Position to show the popup window at, in screen coordinates.}
+
+\docparam{flags}{Combination of any of the following:}
+\twocolwidtha{8cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\tt wxComboCtrl::ShowAbove}}{Popup is shown above the control instead
+of below.}
+\twocolitem{{\tt wxComboCtrl::CanDeferShow}}{Showing the popup can be deferred
+to happen sometime after \helpref{ShowPopup}{wxcomboctrlshowpopup} has finished.
+In this case, \helpref{AnimateShow}{wxcomboctrlanimateshow} must return \false.}
+\end{twocollist}
+
+
+\membersection{wxComboCtrl::EnablePopupAnimation}\label{wxcomboctrlenablepopupanimation}
+
+\func{void}{EnablePopupAnimation}{\param{bool }{enable = true}}
+
+Enables or disables popup animation, if any, depending on the value of
+the argument.
+
+

 \membersection{wxComboCtrl::GetBitmapDisabled}\label{wxcomboctrlgetbitmapdisabled}
 
 \constfunc{const wxBitmap\&}{GetBitmapDisabled}{\void}
 \membersection{wxComboCtrl::GetBitmapDisabled}\label{wxcomboctrlgetbitmapdisabled}
 
 \constfunc{const wxBitmap\&}{GetBitmapDisabled}{\void}


@@ -289,6 +355,13 @@ Returns depressed button bitmap that has been set with
 A reference to the depressed state bitmap.
 
 
 A reference to the depressed state bitmap.
 
 

+\membersection{wxComboCtrl::GetButtonSize}\label{wxcomboctrlgetbuttonsize}
+
+\func{wxSize}{GetButtonSize}{\void}
+
+Returns current size of the dropdown button.
+
+

 \membersection{wxComboCtrl::GetCustomPaintWidth}\label{wxcomboctrlgetcustompaintwidth}
 
 \constfunc{int}{GetCustomPaintWidth}{\void}
 \membersection{wxComboCtrl::GetCustomPaintWidth}\label{wxcomboctrlgetcustompaintwidth}
 
 \constfunc{int}{GetCustomPaintWidth}{\void}


@@ -327,8 +400,7 @@ itself can be custom painted.}
 \twocolitem{{\tt wxComboCtrlFeatures::PaintWritable}}{A variable-
 width area in front of writable combo control's textctrl can
 be custom painted.}
 \twocolitem{{\tt wxComboCtrlFeatures::PaintWritable}}{A variable-
 width area in front of writable combo control's textctrl can
 be custom painted.}

-\twocolitem{{\tt wxComboCtrlFeatures::Borderless}}{wxNO\_BORDER
-window style works.}
+\twocolitem{{\tt wxComboCtrlFeatures::Borderless}}{wxBORDER\_NONE window style works.}

 \twocolitem{{\tt wxComboCtrlFeatures::All}}{All of the
 above.}
 \end{twocollist}
 \twocolitem{{\tt wxComboCtrlFeatures::All}}{All of the
 above.}
 \end{twocollist}


@@ -344,6 +416,22 @@ Returns the insertion point for the combo control's text field.
 doesn't have the focus.
 
 
 doesn't have the focus.
 
 

+\membersection{wxComboCtrl::IsPopupWindowState}\label{wxcomboctrlispopupwindowstate}
+
+\constfunc{bool}{IsPopupWindowState}{\param{int }{state}}
+
+Returns \true if the popup window is in the given state.
+Possible values are:
+\twocolwidtha{8cm}%
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\tt wxComboCtrl::Hidden}}{Popup window is hidden.}
+\twocolitem{{\tt wxComboCtrl::Animating}}{Popup window is being shown, but the
+popup animation has not yet finished.}
+\twocolitem{{\tt wxComboCtrl::Visible}}{Popup window is fully visible.}
+\end{twocollist}
+
+
+

 \membersection{wxComboCtrl::GetLastPosition}\label{wxcomboctrlgetlastposition}
 
 \constfunc{long}{GetLastPosition}{\void}
 \membersection{wxComboCtrl::GetLastPosition}\label{wxcomboctrlgetlastposition}
 
 \constfunc{long}{GetLastPosition}{\void}


@@ -379,6 +467,14 @@ Get the text control which is part of the combo control.
 Returns actual indentation in pixels.
 
 
 Returns actual indentation in pixels.
 
 

+\membersection{wxComboCtrl::GetTextRect}\label{wxcomboctrlgettextrect}
+
+\constfunc{const wxRect\&}{GetTextRect}{\void}
+
+Returns area covered by the text field (includes everything except
+borders and the dropdown button).
+
+

 \membersection{wxComboCtrl::GetValue}\label{wxcomboctrlgetvalue}
 
 \constfunc{wxString}{GetValue}{\void}
 \membersection{wxComboCtrl::GetValue}\label{wxcomboctrlgetvalue}
 
 \constfunc{wxString}{GetValue}{\void}


@@ -410,6 +506,11 @@ dropdown button click.
 
 Default action is to show the popup.
 
 
 Default action is to show the popup.
 

+\textbf{Note:} If you implement this to do something else than
+show the popup, you must then also implement
+\helpref{DoSetPopupControl}{wxcomboctrldosetpopupcontrol} to always
+return NULL.
+

 
 \membersection{wxComboCtrl::Paste}\label{wxcomboctrlpaste}
 
 
 \membersection{wxComboCtrl::Paste}\label{wxcomboctrlpaste}
 


@@ -466,15 +567,14 @@ different kind of button on mouse hover.}
 
 \membersection{wxComboCtrl::SetButtonPosition}\label{wxcomboctrlsetbuttonposition}
 
 
 \membersection{wxComboCtrl::SetButtonPosition}\label{wxcomboctrlsetbuttonposition}
 

-\func{void}{SetButtonPosition}{\param{int }{width = 0}, \param{int }{height = 0}, \param{int }{side = wxRIGHT}, \param{int }{spacingX = 0}}
+\func{void}{SetButtonPosition}{\param{int }{width = -1}, \param{int }{height = -1}, \param{int }{side = wxRIGHT}, \param{int }{spacingX = 0}}

 
 Sets size and position of dropdown button.
 
 \wxheading{Parameters}
 
 
 Sets size and position of dropdown button.
 
 \wxheading{Parameters}
 

-\docparam{width}{If > $0$, defines specific button width. $0$ means platform default,
-while negative numbers allow adjusting smaller than default.}
-\docparam{height}{Same as width.}
+\docparam{width}{Button width. Value <= $0$ specifies default.}
+\docparam{height}{Button height. Value <= $0$ specifies default.}

 \docparam{side}{Indicates which side the button will be placed.
 Value can be {\tt wxLEFT} or {\tt wxRIGHT}.}
 \docparam{spacingX}{Horizontal spacing around the button. Default is $0$.}
 \docparam{side}{Indicates which side the button will be placed.
 Value can be {\tt wxLEFT} or {\tt wxRIGHT}.}
 \docparam{spacingX}{Horizontal spacing around the button. Default is $0$.}


@@ -614,6 +714,14 @@ string must be accepted by the popup (for instance, exist in the dropdown
 list), otherwise the call to SetValue() is ignored
 
 
 list), otherwise the call to SetValue() is ignored
 
 

+\membersection{wxComboCtrl::SetValueWithEvent}\label{wxcomboctrlsetvaluewithevent}
+
+\func{void}{SetValueWithEvent}{\param{const wxString\& }{value}, \param{bool }{withEvent = true}}
+
+Same as SetValue, but also sends wxCommandEvent of type wxEVT\_COMMAND\_TEXT\_UPDATED
+if {\tt withEvent} is \true.
+
+

 \membersection{wxComboCtrl::ShowPopup}\label{wxcomboctrlshowpopup}
 
 \func{void}{ShowPopup}{\void}
 \membersection{wxComboCtrl::ShowPopup}\label{wxcomboctrlshowpopup}
 
 \func{void}{ShowPopup}{\void}


@@ -626,3 +734,16 @@ Show the popup.
 \func{void}{Undo}{\void}
 
 Undoes the last edit in the text field. Windows only.
 \func{void}{Undo}{\void}
 
 Undoes the last edit in the text field. Windows only.

+
+
+\membersection{wxComboCtrl::UseAltPopupWindow}\label{wxcomboctrlusealtpopupwindow}
+
+\func{void}{UseAltPopupWindow}{\param{bool }{enable = true}}
+
+Enable or disable usage of an alternative popup window, which guarantees
+ability to focus the popup control, and allows common native controls to
+function normally. This alternative popup window is usually a wxDialog,
+and as such, when it is shown, its parent top-level window will appear
+as if the focus has been lost from it.
+
+