From c2709a3dd79dafe9f497b670e03036b0788e77f1 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 8 Oct 2006 15:12:54 +0000 Subject: [PATCH] document wxAboutBox &c git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@41720 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/changes.txt | 1 + docs/latex/wx/aboutdlginfo.tex | 224 +++++++++++++++++++++++++++++++++ docs/latex/wx/function.tex | 58 +++++++++ 3 files changed, 283 insertions(+) create mode 100644 docs/latex/wx/aboutdlginfo.tex diff --git a/docs/changes.txt b/docs/changes.txt index b72835a0b5..856405f603 100644 --- a/docs/changes.txt +++ b/docs/changes.txt @@ -66,6 +66,7 @@ All (GUI): - Support for right-to-left text layout (started by Diaa Sami during Google Summer of Code, with a lot of help from Tim Kosse and others). +- Added wxAboutBox() function for displaying the standard about dialog - Added wxID_PAGE_SETUP standard id. - Added wxSize::IncBy() and DecBy() methods. - Added file type parameter to wxTextCtrl::LoadFile, wxTextCtrl::SaveFile for diff --git a/docs/latex/wx/aboutdlginfo.tex b/docs/latex/wx/aboutdlginfo.tex new file mode 100644 index 0000000000..b575fa2fb9 --- /dev/null +++ b/docs/latex/wx/aboutdlginfo.tex @@ -0,0 +1,224 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: aboutdlginfo.tex +%% Purpose: wxAboutDialogInfo documentation +%% Author: Vadim Zeitlin +%% Created: 2006-10-08 +%% RCS-ID: $Id$ +%% Copyright: (c) Vadim Zeitlin +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{\class{wxAboutDialogInfo}}\label{wxaboutdialoginfo} + +wxAboutDialogInfo contains information shown in the standard \textit{About} +dialog displayed by the \helpref{wxAboutBox()}{wxaboutbox} function. + +This class contains the general information about the program, such as its +name, version, copyright and so on, as well as lists of the program developers, +documentation writers, artists and translators. The simple properties from the +former group are represented as a string with the exception of the program icon +and the program web site, while the lists from the latter group are stored as +\helpref{wxArrayString}{wxarraystring} and can be either set entirely at once +using \helpref{SetDevelopers}{wxaboutdialoginfosetdevelopers} and similar +functions or built one by one using \helpref{AddDeveloper}{wxaboutdialoginfoadddeveloper} +etc. + +Please also notice that while all the main platforms have the native +implementation of the about dialog, they are often more limited than the +generic version provided by wxWidgets and so the generic version is used if +wxAboutDialogInfo has any fields not supported by the native version. Currently +GTK+ version supports all the possible fields natively but MSW and Mac versions +don't support URLs, licence text nor custom icons in the about dialog and if +either of those is used, \helpref{wxAboutBox()}{wxaboutbox} will automatically +use the generic version so you should avoid specifying these fields to achieve +more native look and feel. + +\wxheading{Derived from} + +No base class + +\wxheading{Include files} + + + + +\latexignore{\rtfignore{\wxheading{Members}}} + + +\membersection{wxAboutDialogInfo::wxAboutDialogInfo}\label{wxaboutdialoginfowxaboutdialoginfo} + +\func{}{wxAboutDialogInfo}{\void} + +Default constructor leaves all fields are initially uninitialized, in general +you should call at least \helpref{SetVersion}{wxaboutdialoginfosetversion}, +\helpref{SetCopyright}{wxaboutdialoginfosetcopyright} and +\helpref{SetDescription}{wxaboutdialoginfosetdescription}. + + +\membersection{wxAboutDialogInfo::AddArtist}\label{wxaboutdialoginfoaddartist} + +\func{void}{AddArtist}{\param{const wxString\& }{artist}} + +Adds an artist name to be shown in the program credits. + +\wxheading{See also} + +\helpref{SetArtists}{wxaboutdialoginfosetartists} + + +\membersection{wxAboutDialogInfo::AddDeveloper}\label{wxaboutdialoginfoadddeveloper} + +\func{void}{AddDeveloper}{\param{const wxString\& }{developer}} + +Adds a developer name to be shown in the program credits. + +\wxheading{See also} + +\helpref{SetDevelopers}{wxaboutdialoginfosetdevelopers} + + +\membersection{wxAboutDialogInfo::AddDocWriter}\label{wxaboutdialoginfoadddocwriter} + +\func{void}{AddDocWriter}{\param{const wxString\& }{docwriter}} + +Adds a documentation writer name to be shown in the program credits. + +\wxheading{See also} + +\helpref{SetDocWriters}{wxaboutdialoginfosetdocwriters} + + +\membersection{wxAboutDialogInfo::AddTranslator}\label{wxaboutdialoginfoaddtranslator} + +\func{void}{AddTranslator}{\param{const wxString\& }{translator}} + +Adds a translator name to be shown in the program credits. Notice that if no +translator names are specified explicitely, \helpref{wxAboutBox()}{wxaboutbox} +will try to use the translation of the string \texttt{translator-credits} from +the currently used message catalog -- this can be used to show just the name of +the translator of the program in the current language. + +\wxheading{See also} + +\helpref{SetTranslators}{wxaboutdialoginfosettranslators} + + +\membersection{wxAboutDialogInfo::SetArtists}\label{wxaboutdialoginfosetartists} + +\func{void}{SetArtists}{\param{const wxArrayString\& }{artists}} + +Sets the the list of artists to be shown in the program credits. + +\wxheading{See also} + +\helpref{AddArtist}{wxaboutdialoginfoaddartist} + + +\membersection{wxAboutDialogInfo::SetCopyright}\label{wxaboutdialoginfosetcopyright} + +\func{void}{SetCopyright}{\param{const wxString\& }{copyright}} + +Set the short string containing the program copyright information. Notice that +any occurrences of \texttt{"(C)"} in \arg{copyright} will be replaced by the +copyright symbol (circled C) automatically, which means that you can avoid +using this symbol in the program source code which can be problematic, + + +\membersection{wxAboutDialogInfo::SetDescription}\label{wxaboutdialoginfosetdescription} + +\func{void}{SetDescription}{\param{const wxString\& }{desc}} + +Set brief, but possibly multiline, description of the program. + + +\membersection{wxAboutDialogInfo::SetDevelopers}\label{wxaboutdialoginfosetdevelopers} + +\func{void}{SetDevelopers}{\param{const wxArrayString\& }{developers}} + +Set the list of developers of the program. + +\wxheading{See also} + +\helpref{AddDeveloper}{wxaboutdialoginfoadddeveloper} + + +\membersection{wxAboutDialogInfo::SetDocWriters}\label{wxaboutdialoginfosetdocwriters} + +\func{void}{SetDocWriters}{\param{const wxArrayString\& }{docwriters}} + +Set the list of documentation writers. + +\wxheading{See also} + +\helpref{AddDocWriter}{wxaboutdialoginfoadddocwriter} + + +\membersection{wxAboutDialogInfo::SetIcon}\label{wxaboutdialoginfoseticon} + +\func{void}{SetIcon}{\param{const wxIcon\& }{icon}} + +Set the icon to be shown in the dialog. By default the icon of the main frame +will be shown if the native about dialog supports custom icons. If it doesn't +but a valid icon is specified using this method, the generic about dialog is +used instead so you should avoid calling this function for maximally native +look and feel. + + +\membersection{wxAboutDialogInfo::SetLicence}\label{wxaboutdialoginfosetlicence} + +\func{void}{SetLicence}{\param{const wxString\& }{licence}} + +Set the long, multiline string containing the text of the program licence. + +Only GTK+ version supports showing the licence text in the native about dialog +currently so the generic version will be used under all the other platforms if +this method is called. To preserve the native look and feel it is advised that +you do not call this method but provide a separate menu item in the +\texttt{"Help"} menu for displaying the text of your program licence. + + +\membersection{wxAboutDialogInfo::SetLicense}\label{wxaboutdialoginfosetlicense} + +\func{void}{SetLicense}{\param{const wxString\& }{licence}} + +This is the same as \helpref{SetLicence}{wxaboutdialoginfosetlicence}. + + +\membersection{wxAboutDialogInfo::SetName}\label{wxaboutdialoginfosetname} + +\func{void}{SetName}{\param{const wxString\& }{name}} + +Set the name of the program. If this method is not called, the string returned +by \helpref{wxApp::GetAppName()}{wxappgetappname} will be shown in the dialog. + + +\membersection{wxAboutDialogInfo::SetTranslators}\label{wxaboutdialoginfosettranslators} + +\func{void}{SetTranslators}{\param{const wxArrayString\& }{translators}} + +Set the list of translators. Please see +\helpref{AddTranslator}{wxaboutdialoginfoaddtranslator} for additional +discussion. + + +\membersection{wxAboutDialogInfo::SetVersion}\label{wxaboutdialoginfosetversion} + +\func{void}{SetVersion}{\param{const wxString\& }{version}} + +Set the version of the program. The version is in free format, i.e. not +necessarily in the \texttt{x.y.z} form but it shouldn't contain the "version" +word. + + +\membersection{wxAboutDialogInfo::SetWebSite}\label{wxaboutdialoginfosetwebsite} + +\func{void}{SetWebSite}{\param{const wxString\& }{url}, \param{const wxString\& }{desc = wxEmptyString}} + +Set the web site for the program and its description (which defaults to URL +itself if empty). + +Please notice that only GTK+ version currently supports showing the link in the +native about dialog so if this method is called, the generic version will be +used under all the other platforms. + + diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex index ad5237aaf4..0863f28a83 100644 --- a/docs/latex/wx/function.tex +++ b/docs/latex/wx/function.tex @@ -32,6 +32,7 @@ the corresponding topic. \helpref{IMPLEMENT\_CLASS}{implementclass}\\ \helpref{IMPLEMENT\_DYNAMIC\_CLASS2}{implementdynamicclass2}\\ \helpref{IMPLEMENT\_DYNAMIC\_CLASS}{implementdynamicclass}\\ +\helpref{wxAboutBox}{wxaboutbox}\\ \helpref{wxASSERT}{wxassert}\\ \helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\ \helpref{wxASSERT\_MSG}{wxassertmsg}\\ @@ -103,6 +104,7 @@ the corresponding topic. \helpref{wxFindWindowByLabel}{wxfindwindowbylabel}\\ \helpref{wxFindWindowByName}{wxfindwindowbyname}\\ \helpref{wxFinite}{wxfinite}\\ +\helpref{wxGenericAboutBox}{wxgenericaboutbox}\\ \helpref{wxGetActiveWindow}{wxgetactivewindow}\\ \helpref{wxGetApp}{wxgetapp}\\ \helpref{wxGetBatteryState}{wxgetbatterystate}\\ @@ -1804,6 +1806,39 @@ parameter, or (in MS Windows or Motif) the wrong window frame may be brought to the front when the dialog box is popped up. +\membersection{::wxAboutBox}\label{wxaboutbox} + +\func{void}{wxAboutBox}{\param{const wxAboutDialogInfo\& }{info}} + +This function shows the standard about dialog containing the information +specified in \arg{info}. If the current platform has a native about dialog +which is capable of showing all the fields in \arg{info}, the native dialog is +used, otherwise the function falls back to the generic wxWidgets version of the +dialog, i.e. does the same thing as \helpref{wxGenericAboutBox()}{wxgenericaboutbox}. + +Here is an example of how this function may be used: +\begin{verbatim} +void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event)) +{ + wxAboutDialogInfo info; + info.SetName(_("My Program")); + info.SetVersion(_("1.2.3 Beta")); + info.SetDescription(_("This program does something great.")); + info.SetCopyright(_T("(C) 2007 Me ")); + + wxAboutBox(info); +} +\end{verbatim} + +Please see the \helpref{dialogs sample}{sampledialogs} for more examples of +using this function and \helpref{wxAboutDialogInfo}{wxaboutdialoginfo} for the +description of the information which can be shown in the about dialog. + +\wxheading{Include files} + + + + \membersection{::wxBeginBusyCursor}\label{wxbeginbusycursor} \func{void}{wxBeginBusyCursor}{\param{wxCursor *}{cursor = wxHOURGLASS\_CURSOR}} @@ -1941,6 +1976,29 @@ See also \helpref{wxIsBusy}{wxisbusy}, \helpref{wxBusyCursor}{wxbusycursor}. +\membersection{::wxGenericAboutBox}\label{wxgenericaboutbox} + +\func{void}{wxGenericAboutBox}{\param{const wxAboutDialogInfo\& }{info}} + +This function does the same thing as \helpref{wxAboutBox}{wxaboutbox} except +that it always uses the generic wxWidgets version of the dialog instead of the +native one. This is mainly useful if you need to customize the dialog by e.g. +adding custom controls to it (customizing the native dialog is not currently +supported). + +See the \helpref{dialogs sample}{sampledialogs} for an example of about dialog +customization. + +\wxheading{See also} + +\helpref{wxAboutDialogInfo}{wxaboutdialoginfo} + +\wxheading{Include files} + + + + + \membersection{::wxGetColourFromUser}\label{wxgetcolourfromuser} \func{wxColour}{wxGetColourFromUser}{\param{wxWindow *}{parent}, \param{const wxColour\& }{colInit}, \param{const wxString\& }{caption = wxEmptyString}} -- 2.45.2