Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

remove the 1-space indentation from remaining pages; mark with @todo tags parts of the docs which need to be written yet

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52706 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-03-22 17:49:09 +00:00
parent dc28cdf8d4
commit 928f1a076c
28 changed files with 3869 additions and 3866 deletions
Download Patch File Download Diff File Expand all files Collapse all files

328
docs/doxygen/overviews/datetime.h
View File

@@ -8,237 +8,237 @@
/**
@page overview_datetime Date and Time
@page overview_datetime Date and Time
Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl
Classes: wxDateTime, wxDateSpan, wxTimeSpan, wxCalendarCtrl
@li @ref overview_datetime_introduction
@li @ref overview_datetime_classes
@li @ref overview_datetime_characteristics
@li @ref overview_datetime_timespandiff
@li @ref overview_datetime_arithmetics
@li @ref overview_datetime_timezones
@li @ref overview_datetime_dst
@li @ref overview_datetime_holidays
@li @ref overview_datetime_compat
@li @ref overview_datetime_introduction
@li @ref overview_datetime_classes
@li @ref overview_datetime_characteristics
@li @ref overview_datetime_timespandiff
@li @ref overview_datetime_arithmetics
@li @ref overview_datetime_timezones
@li @ref overview_datetime_dst
@li @ref overview_datetime_holidays
@li @ref overview_datetime_compat
<hr>
<hr>
@section overview_datetime_introduction Introduction
@section overview_datetime_introduction Introduction
wxWidgets provides a set of powerful classes to work with dates and times. Some
of the supported features of wxDateTime class are:
wxWidgets provides a set of powerful classes to work with dates and times. Some
of the supported features of wxDateTime class are:
@li Wide range: the range of supported dates goes from about 4714 B.C. to
some 480 million years in the future.
@li Wide range: the range of supported dates goes from about 4714 B.C. to
some 480 million years in the future.
@li Precision: not using floating point calculations anywhere ensures that
the date calculations don't suffer from rounding errors.
@li Precision: not using floating point calculations anywhere ensures that
the date calculations don't suffer from rounding errors.
@li Many features: not only all usual calculations with dates are supported,
but also more exotic week and year day calculations, work day testing, standard
astronomical functions, conversion to and from strings in either strict or free
@li Many features: not only all usual calculations with dates are supported,
but also more exotic week and year day calculations, work day testing, standard
astronomical functions, conversion to and from strings in either strict or free
format.
@li Efficiency: objects of wxDateTime are small (8 bytes) and working with
them is fast
@li Efficiency: objects of wxDateTime are small (8 bytes) and working with
them is fast
@section overview_datetime_classes All date/time classes at a glance
@section overview_datetime_classes All date/time classes at a glance
There are 3 main classes declared in @c wx/datetime.h: except wxDateTime itself
which represents an absolute moment in time, there are also two classes -
wxTimeSpan and wxDateSpan - which represent the intervals of time.
There are 3 main classes declared in @c wx/datetime.h: except wxDateTime itself
which represents an absolute moment in time, there are also two classes -
wxTimeSpan and wxDateSpan - which represent the intervals of time.
There are also helper classes which are used together with wxDateTime:
wxDateTimeHolidayAuthority which is used to determine whether a given date
is a holiday or not and wxDateTimeWorkDays which is a derivation of this
class for which (only) Saturdays and Sundays are the holidays. See more about
these classes in the discussion of the holidays (see @ref overview_datetime_holidays).
There are also helper classes which are used together with wxDateTime:
wxDateTimeHolidayAuthority which is used to determine whether a given date
is a holiday or not and wxDateTimeWorkDays which is a derivation of this
class for which (only) Saturdays and Sundays are the holidays. See more about
these classes in the discussion of the holidays (see @ref overview_datetime_holidays).
Finally, in other parts of this manual you may find mentions of wxDate and
wxTime classes. @ref overview_datetime_compat are obsolete and
superseded by wxDateTime.
Finally, in other parts of this manual you may find mentions of wxDate and
wxTime classes. @ref overview_datetime_compat are obsolete and
superseded by wxDateTime.
@section overview_datetime_characteristics wxDateTime characteristics
@section overview_datetime_characteristics wxDateTime characteristics
wxDateTime stores the time as a signed number of
milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
however this is not visible to the class users (in particular, dates prior to
the Epoch are handled just as well (or as bad) as the dates after it). But it
does mean that the best resolution which can be achieved with this class is 1
millisecond.
wxDateTime stores the time as a signed number of
milliseconds since the Epoch which is fixed, by convention, to Jan 1, 1970 -
however this is not visible to the class users (in particular, dates prior to
the Epoch are handled just as well (or as bad) as the dates after it). But it
does mean that the best resolution which can be achieved with this class is 1
millisecond.
The size of wxDateTime object is 8 bytes because it is represented as a 64 bit
integer. The resulting range of supported dates is thus approximatively 580
million years, but due to the current limitations in the Gregorian calendar
support, only dates from Nov 24, 4714BC are supported (this is subject to
change if there is sufficient interest in doing it).
The size of wxDateTime object is 8 bytes because it is represented as a 64 bit
integer. The resulting range of supported dates is thus approximatively 580
million years, but due to the current limitations in the Gregorian calendar
support, only dates from Nov 24, 4714BC are supported (this is subject to
change if there is sufficient interest in doing it).
Finally, the internal representation is time zone independent (always in GMT)
and the time zones only come into play when a date is broken into
year/month/day components. See more about timezones below
(see @ref overview_datetime_timezones).
Finally, the internal representation is time zone independent (always in GMT)
and the time zones only come into play when a date is broken into
year/month/day components. See more about timezones below
(see @ref overview_datetime_timezones).
Currently, the only supported calendar is Gregorian one (which is used even
for the dates prior to the historic introduction of this calendar which was
first done on Oct 15, 1582 but is, generally speaking, country, and even
region, dependent). Future versions will probably have Julian calendar support
as well and support for other calendars (Maya, Hebrew, Chinese...) is not
ruled out.
Currently, the only supported calendar is Gregorian one (which is used even
for the dates prior to the historic introduction of this calendar which was
first done on Oct 15, 1582 but is, generally speaking, country, and even
region, dependent). Future versions will probably have Julian calendar support
as well and support for other calendars (Maya, Hebrew, Chinese...) is not
ruled out.
@section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan
@section overview_datetime_timespandiff Difference between wxDateSpan and wxTimeSpan
While there is only one logical way to represent an absolute moment in the
time (and hence only one wxDateTime class), there are at least two methods to
describe a time interval.
While there is only one logical way to represent an absolute moment in the
time (and hence only one wxDateTime class), there are at least two methods to
describe a time interval.
First, there is the direct and self-explaining way implemented by
wxTimeSpan: it is just a difference in milliseconds
between two moments in time. Adding or subtracting such an interval to
wxDateTime is always well-defined and is a fast operation.
First, there is the direct and self-explaining way implemented by
wxTimeSpan: it is just a difference in milliseconds
between two moments in time. Adding or subtracting such an interval to
wxDateTime is always well-defined and is a fast operation.
But in the daily life other, calendar-dependent time interval specifications are
used. For example, 'one month later' is commonly used. However, it is clear
that this is not the same as wxTimeSpan of 60*60*24*31 seconds because 'one
month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether
the year is leap or not).
But in the daily life other, calendar-dependent time interval specifications are
used. For example, 'one month later' is commonly used. However, it is clear
that this is not the same as wxTimeSpan of 60*60*24*31 seconds because 'one
month later' Feb 15 is Mar 15 and not Mar 17 or Mar 16 (depending on whether
the year is leap or not).
This is why there is another class for representing such intervals called
wxDateSpan. It handles these sort of operations in the
most natural way possible, but note that manipulating with intervals of
this kind is not always well-defined. Consider, for example, Jan 31 + '1
month': this will give Feb 28 (or 29), i.e. the last day of February and not
the non-existent Feb 31. Of course, this is what is usually wanted, but you
still might be surprised to notice that now subtracting back the same
interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started
with!
This is why there is another class for representing such intervals called
wxDateSpan. It handles these sort of operations in the
most natural way possible, but note that manipulating with intervals of
this kind is not always well-defined. Consider, for example, Jan 31 + '1
month': this will give Feb 28 (or 29), i.e. the last day of February and not
the non-existent Feb 31. Of course, this is what is usually wanted, but you
still might be surprised to notice that now subtracting back the same
interval from Feb 28 will result in Jan 28 and @b not Jan 31 we started
with!
So, unless you plan to implement some kind of natural language parsing in the
program, you should probably use wxTimeSpan instead of wxDateSpan (which is
also more efficient). However, wxDateSpan may be very useful in situations
when you do need to understand what 'in a month' means (of course, it is
just @c wxDateTime::Now() + wxDateSpan::Month()).
So, unless you plan to implement some kind of natural language parsing in the
program, you should probably use wxTimeSpan instead of wxDateSpan (which is
also more efficient). However, wxDateSpan may be very useful in situations
when you do need to understand what 'in a month' means (of course, it is
just @c wxDateTime::Now() + wxDateSpan::Month()).
@section overview_datetime_arithmetics Date arithmetics
@section overview_datetime_arithmetics Date arithmetics
Many different operations may be performed with the dates, however not all of
them make sense. For example, multiplying a date by a number is an invalid
operation, even though multiplying either of the time span classes by a number
is perfectly valid.
Many different operations may be performed with the dates, however not all of
them make sense. For example, multiplying a date by a number is an invalid
operation, even though multiplying either of the time span classes by a number
is perfectly valid.
Here is what can be done:
Here is what can be done:
@li @b Addition: a wxTimeSpan or wxDateSpan can be added to wxDateTime
resulting in a new wxDateTime object and also 2 objects of the same span class
can be added together giving another object of the same class.
@li @b Addition: a wxTimeSpan or wxDateSpan can be added to wxDateTime
resulting in a new wxDateTime object and also 2 objects of the same span class
can be added together giving another object of the same class.
@li @b Subtraction: the same types of operations as above are
allowed and, additionally, a difference between two wxDateTime objects can be
taken and this will yield wxTimeSpan.
@li @b Subtraction: the same types of operations as above are
allowed and, additionally, a difference between two wxDateTime objects can be
taken and this will yield wxTimeSpan.
@li @b Multiplication: a wxTimeSpan or wxDateSpan object can be
multiplied by an integer number resulting in an object of the same type.
@li @b Multiplication: a wxTimeSpan or wxDateSpan object can be
multiplied by an integer number resulting in an object of the same type.
@li <b>Unary minus</b>: a wxTimeSpan or wxDateSpan object may finally be
negated giving an interval of the same magnitude but of opposite time
direction.
@li <b>Unary minus</b>: a wxTimeSpan or wxDateSpan object may finally be
negated giving an interval of the same magnitude but of opposite time
direction.
For all these operations there are corresponding global (overloaded) operators
and also member functions which are synonyms for them: Add(), Subtract() and
Multiply(). Unary minus as well as composite assignment operations (like +=)
are only implemented as members and Neg() is the synonym for unary minus.
For all these operations there are corresponding global (overloaded) operators
and also member functions which are synonyms for them: Add(), Subtract() and
Multiply(). Unary minus as well as composite assignment operations (like +=)
are only implemented as members and Neg() is the synonym for unary minus.
@section overview_datetime_timezones Time zone considerations
@section overview_datetime_timezones Time zone considerations
Although the time is always stored internally in GMT, you will usually work in
the local time zone. Because of this, all wxDateTime constructors and setters
which take the broken down date assume that these values are for the local
time zone. Thus, @c wxDateTime(1, wxDateTime::Jan, 1970) will not
correspond to the wxDateTime Epoch unless you happen to live in the UK.
All methods returning the date components (year, month, day, hour, minute,
second...) will also return the correct values for the local time zone by
default, so, generally, doing the natural things will lead to natural and
correct results.
Although the time is always stored internally in GMT, you will usually work in
the local time zone. Because of this, all wxDateTime constructors and setters
which take the broken down date assume that these values are for the local
time zone. Thus, @c wxDateTime(1, wxDateTime::Jan, 1970) will not
correspond to the wxDateTime Epoch unless you happen to live in the UK.
All methods returning the date components (year, month, day, hour, minute,
second...) will also return the correct values for the local time zone by
default, so, generally, doing the natural things will lead to natural and
correct results.
If you only want to do this, you may safely skip the rest of this section.
However, if you want to work with different time zones, you should read it to
the end.
If you only want to do this, you may safely skip the rest of this section.
However, if you want to work with different time zones, you should read it to
the end.
In this (rare) case, you are still limited to the local time zone when
constructing wxDateTime objects, i.e. there is no way to construct a
wxDateTime corresponding to the given date in, say, Pacific Standard Time.
To do it, you will need to call wxDateTime::ToTimezone or wxDateTime::MakeTimezone
methods to adjust the date for the target time zone. There are also special
versions of these functions wxDateTime::ToUTC and wxDateTime::MakeUTC for
the most common case - when the date should be constructed in UTC.
In this (rare) case, you are still limited to the local time zone when
constructing wxDateTime objects, i.e. there is no way to construct a
wxDateTime corresponding to the given date in, say, Pacific Standard Time.
To do it, you will need to call wxDateTime::ToTimezone or wxDateTime::MakeTimezone
methods to adjust the date for the target time zone. There are also special
versions of these functions wxDateTime::ToUTC and wxDateTime::MakeUTC for
the most common case - when the date should be constructed in UTC.
You also can just retrieve the value for some time zone without converting the
object to it first. For this you may pass TimeZone argument to any of the
methods which are affected by the time zone (all methods getting date
components and the date formatting ones, for example). In particular, the
Format() family of methods accepts a TimeZone parameter and this allows to
simply print time in any time zone.
You also can just retrieve the value for some time zone without converting the
object to it first. For this you may pass TimeZone argument to any of the
methods which are affected by the time zone (all methods getting date
components and the date formatting ones, for example). In particular, the
Format() family of methods accepts a TimeZone parameter and this allows to
simply print time in any time zone.
To see how to do it, the last issue to address is how to construct a TimeZone
object which must be passed to all these methods. First of all, you may construct
it manually by specifying the time zone offset in seconds from GMT, but
usually you will just use one of the @ref overview_datetime and
let the conversion constructor do the job.
To see how to do it, the last issue to address is how to construct a TimeZone
object which must be passed to all these methods. First of all, you may construct
it manually by specifying the time zone offset in seconds from GMT, but
usually you will just use one of the @ref overview_datetime and
let the conversion constructor do the job.
I.e. you would just write
I.e. you would just write
@code
wxDateTime dt(...whatever...);
printf("The time is %s in local time zone", dt.FormatTime().c_str());
printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());
@endcode
@code
wxDateTime dt(...whatever...);
printf("The time is %s in local time zone", dt.FormatTime().c_str());
printf("The time is %s in GMT", dt.FormatTime(wxDateTime::GMT).c_str());
@endcode
@section overview_datetime_dst Daylight saving time (DST)
@section overview_datetime_dst Daylight saving time (DST)
DST (a.k.a. 'summer time') handling is always a delicate task which is better
left to the operating system which is supposed to be configured by the
administrator to behave correctly. Unfortunately, when doing calculations with
date outside of the range supported by the standard library, we are forced to
deal with these issues ourselves.
DST (a.k.a. 'summer time') handling is always a delicate task which is better
left to the operating system which is supposed to be configured by the
administrator to behave correctly. Unfortunately, when doing calculations with
date outside of the range supported by the standard library, we are forced to
deal with these issues ourselves.
Several functions are provided to calculate the beginning and end of DST in
the given year and to determine whether it is in effect at the given moment or
not, but they should not be considered as absolutely correct because, first of
all, they only work more or less correctly for only a handful of countries
(any information about other ones appreciated!) and even for them the rules
may perfectly well change in the future.
Several functions are provided to calculate the beginning and end of DST in
the given year and to determine whether it is in effect at the given moment or
not, but they should not be considered as absolutely correct because, first of
all, they only work more or less correctly for only a handful of countries
(any information about other ones appreciated!) and even for them the rules
may perfectly well change in the future.
The time zone handling methods (see @ref overview_datetime_timezones) use
these functions too, so they are subject to the same limitations.
The time zone handling methods (see @ref overview_datetime_timezones) use
these functions too, so they are subject to the same limitations.
@section overview_datetime_holidays wxDateTime and Holidays
@section overview_datetime_holidays wxDateTime and Holidays
TODO.
@todo WRITE THIS DOC PARAGRAPH.
@section overview_datetime_compat Compatibility
@section overview_datetime_compat Compatibility
The old classes for date/time manipulations ported from wxWidgets version 1.xx
are still included but are reimplemented in terms of wxDateTime. However, using
them is strongly discouraged because they have a few quirks/bugs and were not
'Y2K' compatible.
The old classes for date/time manipulations ported from wxWidgets version 1.xx
are still included but are reimplemented in terms of wxDateTime. However, using
them is strongly discouraged because they have a few quirks/bugs and were not
'Y2K' compatible.
*/

62
docs/doxygen/overviews/dc.h
View File

@@ -8,44 +8,44 @@
/**
@page overview_dc Device Contexts
@page overview_dc Device Contexts
Classes: wxBufferedDC, wxBufferedPaintDC, wxDC, wxPostScriptDC,
wxMetafileDC, wxMemoryDC, wxPrinterDC, wxScreenDC, wxClientDC,
wxPaintDC, wxWindowDC.
Classes: wxBufferedDC, wxBufferedPaintDC, wxDC, wxPostScriptDC,
wxMetafileDC, wxMemoryDC, wxPrinterDC, wxScreenDC, wxClientDC,
wxPaintDC, wxWindowDC.
A wxDC is a @e device context onto which graphics and text can be drawn.
The device context is intended to represent a number of output devices in a
generic way, with the same API being used throughout.
A wxDC is a @e device context onto which graphics and text can be drawn.
The device context is intended to represent a number of output devices in a
generic way, with the same API being used throughout.
Some device contexts are created temporarily in order to draw on a window.
This is @true of wxScreenDC, wxClientDC, wxPaintDC, and wxWindowDC.
The following describes the differences between these device contexts and
when you should use them.
Some device contexts are created temporarily in order to draw on a window.
This is @true of wxScreenDC, wxClientDC, wxPaintDC, and wxWindowDC.
The following describes the differences between these device contexts and
when you should use them.
@li @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
@li @b wxClientDC. Use this to paint on the client area of window (the part without
borders and other decorations), but do not use it from within an wxPaintEvent.
@li @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
within a wxPaintEvent.
@li @b wxWindowDC. Use this to paint on the whole area of a window, including decorations.
This may not be available on non-Windows platforms.
@li @b wxScreenDC. Use this to paint on the screen, as opposed to an individual window.
@li @b wxClientDC. Use this to paint on the client area of window (the part without
borders and other decorations), but do not use it from within an wxPaintEvent.
@li @b wxPaintDC. Use this to paint on the client area of a window, but @e only from
within a wxPaintEvent.
@li @b wxWindowDC. Use this to paint on the whole area of a window, including decorations.
This may not be available on non-Windows platforms.
To use a client, paint or window device context, create an object on the stack with
the window as argument, for example:
To use a client, paint or window device context, create an object on the stack with
the window as argument, for example:
@code
void MyWindow::OnMyCmd(wxCommandEvent& event)
{
wxClientDC dc(window);
DrawMyPicture(dc);
}
@endcode
@code
void MyWindow::OnMyCmd(wxCommandEvent& event)
{
wxClientDC dc(window);
DrawMyPicture(dc);
}
@endcode
Try to write code so it is parameterised by wxDC - if you do this, the same piece of code may
write to a number of different devices, by passing a different device context. This doesn't
work for everything (for example not all device contexts support bitmap drawing) but
will work most of the time.
Try to write code so it is parameterised by wxDC - if you do this, the same piece of code may
write to a number of different devices, by passing a different device context. This doesn't
work for everything (for example not all device contexts support bitmap drawing) but
will work most of the time.
*/

178
docs/doxygen/overviews/debugging.h
View File

@@ -8,137 +8,137 @@
/**
@page overview_debugging Debugging
@page overview_debugging Debugging
Classes, functions and macros: wxDebugContext, wxObject, wxLog,
Classes, functions and macros: wxDebugContext, wxObject, wxLog,
@ref page_func_cat_log, @ref page_macro_cat_debugging
Various classes, functions and macros are provided in wxWidgets to help you debug
your application. Most of these are only available if you compile both wxWidgets,
your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol
defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
code that should be active only in debug mode.
Various classes, functions and macros are provided in wxWidgets to help you debug
your application. Most of these are only available if you compile both wxWidgets,
your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol
defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
code that should be active only in debug mode.
@li @ref overview_debugging_dbgctx
@li @ref overview_debugging_dbgmacros
@li @ref overview_debugging_logging
@li @ref overview_debugging_dbgctx2
@li @ref overview_debugging_dbgctx
@li @ref overview_debugging_dbgmacros
@li @ref overview_debugging_logging
@li @ref overview_debugging_dbgctx2
<hr>
<hr>
@section overview_debugging_dbgctx wxDebugContext
@section overview_debugging_dbgctx wxDebugContext
wxDebugContext is a class that never gets instantiated, but ties together
various static functions and variables. It allows you to dump all objects to that stream,
write statistics about object allocation, and check memory for errors.
wxDebugContext is a class that never gets instantiated, but ties together
various static functions and variables. It allows you to dump all objects to that stream,
write statistics about object allocation, and check memory for errors.
It is good practice to define a wxObject::Dump member function for each class you derive
from a wxWidgets class, so that wxDebugContext::Dump can call it and
give valuable information about the state of the application.
It is good practice to define a wxObject::Dump member function for each class you derive
from a wxWidgets class, so that wxDebugContext::Dump can call it and
give valuable information about the state of the application.
If you have difficulty tracking down a memory leak, recompile
in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
appropriate places. They will tell you what objects have not yet been
deleted, and what kinds of object they are. In fact, in debug mode wxWidgets will automatically
detect memory leaks when your application is about to exit, and if there are any leaks,
will give you information about the problem. (How much information depends on the operating system
and compiler -- some systems don't allow all memory logging to be enabled). See the
memcheck sample for example of usage.
If you have difficulty tracking down a memory leak, recompile
in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
appropriate places. They will tell you what objects have not yet been
deleted, and what kinds of object they are. In fact, in debug mode wxWidgets will automatically
detect memory leaks when your application is about to exit, and if there are any leaks,
will give you information about the problem. (How much information depends on the operating system
and compiler -- some systems don't allow all memory logging to be enabled). See the
memcheck sample for example of usage.
For wxDebugContext to do its work, the @e new and @e delete operators for wxObject
have been redefined to store extra information about dynamically allocated objects
(but not statically declared objects).
For wxDebugContext to do its work, the @e new and @e delete operators for wxObject
have been redefined to store extra information about dynamically allocated objects
(but not statically declared objects).
This slows down a debugging version of an application, but can
find difficult-to-detect memory leaks (objects are not
deallocated), overwrites (writing past the end of your object) and
underwrites (writing to memory in front of the object).
This slows down a debugging version of an application, but can
find difficult-to-detect memory leaks (objects are not
deallocated), overwrites (writing past the end of your object) and
underwrites (writing to memory in front of the object).
If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and
wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and
wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
@code
#define new new(__FILE__,__LINE__)
@endcode
@code
#define new new(__FILE__,__LINE__)
@endcode
All occurrences of 'new' in wxWidgets and your own application will use
the overridden form of the operator with two extra arguments. This means that
the debugging output (and error messages reporting memory problems) will tell you what
file and on what line you allocated the object. Unfortunately not all
compilers allow this definition to work properly, but most do.
All occurrences of 'new' in wxWidgets and your own application will use
the overridden form of the operator with two extra arguments. This means that
the debugging output (and error messages reporting memory problems) will tell you what
file and on what line you allocated the object. Unfortunately not all
compilers allow this definition to work properly, but most do.
@section overview_debugging_dbgmacros Debug macros
@section overview_debugging_dbgmacros Debug macros
You should also use @ref page_macro_cat_debugging as part of a 'defensive programming'
strategy, scattering wxASSERTs liberally to test for problems in your code as early as
possible.
Forward thinking will save a surprising amount of time in the long run.
You should also use @ref page_macro_cat_debugging as part of a 'defensive programming'
strategy, scattering wxASSERTs liberally to test for problems in your code as early as
possible.
Forward thinking will save a surprising amount of time in the long run.
#wxASSERT is used to pop up an error message box when a condition
is not @true. You can also use #wxASSERT_MSG to supply your
own helpful error message. For example:
#wxASSERT is used to pop up an error message box when a condition
is not @true. You can also use #wxASSERT_MSG to supply your
own helpful error message. For example:
@code
void MyClass::MyFunction(wxObject* object)
{
wxASSERT_MSG( (object != NULL), "object should not be NULL in MyFunction!" );
@code
void MyClass::MyFunction(wxObject* object)
{
wxASSERT_MSG( (object != NULL), "object should not be NULL in MyFunction!" );
...
};
@endcode
...
};
@endcode
The message box allows you to continue execution or abort the program. If you are running
the application inside a debugger, you will be able to see exactly where the problem was.
The message box allows you to continue execution or abort the program. If you are running
the application inside a debugger, you will be able to see exactly where the problem was.
@section overview_debugging_logging Logging functions
@section overview_debugging_logging Logging functions
You can use the wxLogDebug and wxLogTrace functions to output debugging information in
debug mode; it will do nothing for non-debugging code.
You can use the wxLogDebug and wxLogTrace functions to output debugging information in
debug mode; it will do nothing for non-debugging code.
@section overview_debugging_dbgctx2 wxDebugContext overview
@section overview_debugging_dbgctx2 wxDebugContext overview
Class: wxDebugContext
Class: wxDebugContext
wxDebugContext is a class for performing various debugging and memory tracing operations.
wxDebugContext is a class for performing various debugging and memory tracing operations.
This class has only static data and function members, and there should be
no instances. Probably the most useful members are SetFile (for directing output
to a file, instead of the default standard error or debugger output);
Dump (for dumping the dynamically allocated objects) and PrintStatistics
(for dumping information about allocation of objects). You can also call
Check to check memory blocks for integrity.
This class has only static data and function members, and there should be
no instances. Probably the most useful members are SetFile (for directing output
to a file, instead of the default standard error or debugger output);
Dump (for dumping the dynamically allocated objects) and PrintStatistics
(for dumping information about allocation of objects). You can also call
Check to check memory blocks for integrity.
Here's an example of use. The SetCheckpoint ensures that only the
allocations done after the checkpoint will be dumped.
Here's an example of use. The SetCheckpoint ensures that only the
allocations done after the checkpoint will be dumped.
@code
wxDebugContext::SetCheckpoint();
@code
wxDebugContext::SetCheckpoint();
wxDebugContext::SetFile("c:\\temp\\debug.log");
wxDebugContext::SetFile("c:\\temp\\debug.log");
wxString *thing = new wxString;
wxString *thing = new wxString;
char *ordinaryNonObject = new char[1000];
char *ordinaryNonObject = new char[1000];
wxDebugContext::Dump();
wxDebugContext::PrintStatistics();
@endcode
wxDebugContext::Dump();
wxDebugContext::PrintStatistics();
@endcode
You can use wxDebugContext if __WXDEBUG__ is defined, or you can use it
at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled
in non-debug mode because you may not wish to recompile wxWidgets and your entire application
just to make use of the error logging facility.
You can use wxDebugContext if __WXDEBUG__ is defined, or you can use it
at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled
in non-debug mode because you may not wish to recompile wxWidgets and your entire application
just to make use of the error logging facility.
@note wxDebugContext::SetFile has a problem at present, so use the default stream instead.
Eventually the logging will be done through the wxLog facilities instead.
@note wxDebugContext::SetFile has a problem at present, so use the default stream instead.
Eventually the logging will be done through the wxLog facilities instead.
*/

178
docs/doxygen/overviews/dialog.h
View File

@@ -8,127 +8,127 @@
/**
@page overview_dialog wxDialog Overview
@page overview_dialog wxDialog Overview
Classes: wxDialog, wxDialogLayoutAdapter
Classes: wxDialog, wxDialogLayoutAdapter
A dialog box is similar to a panel, in that it is a window which can
be used for placing controls, with the following exceptions:
A dialog box is similar to a panel, in that it is a window which can
be used for placing controls, with the following exceptions:
@li A surrounding frame is implicitly created.
@li Extra functionality is automatically given to the dialog box,
such as tabbing between items (currently Windows only).
@li If the dialog box is @e modal, the calling program is blocked
until the dialog box is dismissed.
@li A surrounding frame is implicitly created.
@li Extra functionality is automatically given to the dialog box,
such as tabbing between items (currently Windows only).
@li If the dialog box is @e modal, the calling program is blocked
until the dialog box is dismissed.
For a set of dialog convenience functions, including file selection, see
@ref page_func_cat_dialog.
For a set of dialog convenience functions, including file selection, see
@ref page_func_cat_dialog.
See also wxTopLevelWindow and wxWindow for inherited
member functions. Validation of data in controls is covered in @ref overview_validator.
See also wxTopLevelWindow and wxWindow for inherited
member functions. Validation of data in controls is covered in @ref overview_validator.
@li @ref overview_dialog_autoscrolling
@li @ref overview_dialog_autoscrolling
<hr>
<hr>
@section overview_dialog_autoscrolling Automatic scrolling dialogs
@section overview_dialog_autoscrolling Automatic scrolling dialogs
As an ever greater variety of mobile hardware comes to market, it becomes more
imperative for wxWidgets applications to adapt to these platforms without putting
too much burden on the programmer. One area where wxWidgets can help is in adapting
dialogs for the lower resolution screens that inevitably accompany a smaller form factor.
wxDialog therefore supplies a global wxDialogLayoutAdapter class that implements
automatic scrolling adaptation for most sizer-based custom dialogs.
As an ever greater variety of mobile hardware comes to market, it becomes more
imperative for wxWidgets applications to adapt to these platforms without putting
too much burden on the programmer. One area where wxWidgets can help is in adapting
dialogs for the lower resolution screens that inevitably accompany a smaller form factor.
wxDialog therefore supplies a global wxDialogLayoutAdapter class that implements
automatic scrolling adaptation for most sizer-based custom dialogs.
Many applications should therefore be able to adapt to small displays with little
or no work, as far as dialogs are concerned.
By default this adaptation is off. To switch scrolling adaptation on globally in
your application, call the static function wxDialog::EnableLayoutAdaptation passing @true.
You can also adjust adaptation on a per-dialog basis by calling
wxDialog::SetLayoutAdaptationMode with one of @c wxDIALOG_ADAPTATION_MODE_DEFAULT
(use the global setting), @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.
Many applications should therefore be able to adapt to small displays with little
or no work, as far as dialogs are concerned.
By default this adaptation is off. To switch scrolling adaptation on globally in
your application, call the static function wxDialog::EnableLayoutAdaptation passing @true.
You can also adjust adaptation on a per-dialog basis by calling
wxDialog::SetLayoutAdaptationMode with one of @c wxDIALOG_ADAPTATION_MODE_DEFAULT
(use the global setting), @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.
The last two modes override the global adaptation setting.
With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the
standard adapter class wxStandardDialogLayoutAdapter) will make part of the dialog scrolling,
leaving standard buttons in a non-scrolling part at the bottom of the dialog.
This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from
within wxDialog::Show or wxDialog::ShowModal:
The last two modes override the global adaptation setting.
With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the
standard adapter class wxStandardDialogLayoutAdapter) will make part of the dialog scrolling,
leaving standard buttons in a non-scrolling part at the bottom of the dialog.
This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from
within wxDialog::Show or wxDialog::ShowModal:
@li If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase,
the pages are made scrollable and no other adaptation is done.
@li wxWidgets looks for a wxStdDialogButtonSizer and uses it for the non-scrolling part.
@li If that search failed, wxWidgets looks for a horizontal wxBoxSizer with one or more
standard buttons, with identifiers such as @c wxID_OK and @c wxID_CANCEL.
@li If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer)
and adds them to a wxStdDialogButtonSizer.
If no standard buttons were found, the whole dialog content will scroll.
@li All the children apart from standard buttons are reparented onto a new wxScrolledWindow
object, using the old top-level sizer for the scrolled window and creating a new top-level
sizer to lay out the scrolled window and standard button sizer.
@li If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase,
the pages are made scrollable and no other adaptation is done.
@li wxWidgets looks for a wxStdDialogButtonSizer and uses it for the non-scrolling part.
@li If that search failed, wxWidgets looks for a horizontal wxBoxSizer with one or more
standard buttons, with identifiers such as @c wxID_OK and @c wxID_CANCEL.
@li If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer)
and adds them to a wxStdDialogButtonSizer.
If no standard buttons were found, the whole dialog content will scroll.
@li All the children apart from standard buttons are reparented onto a new wxScrolledWindow
object, using the old top-level sizer for the scrolled window and creating a new top-level
sizer to lay out the scrolled window and standard button sizer.
@subsection overview_dialog_autoscrolling_custom Customising scrolling adaptation
@subsection overview_dialog_autoscrolling_custom Customising scrolling adaptation
In addition to switching adaptation on and off globally and per dialog,
you can choose how aggressively wxWidgets will search for standard buttons by setting
wxDialog::SetLayoutAdaptationLevel. By default, all the steps described above will be
performed but by setting the level to 1, for example, you can choose to only look for
wxStdDialogButtonSizer.
In addition to switching adaptation on and off globally and per dialog,
you can choose how aggressively wxWidgets will search for standard buttons by setting
wxDialog::SetLayoutAdaptationLevel. By default, all the steps described above will be
performed but by setting the level to 1, for example, you can choose to only look for
wxStdDialogButtonSizer.
You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
treated as standard buttons for the non-scrolling area.
You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
treated as standard buttons for the non-scrolling area.
You can derive your own class from wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override
the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability
and perform the adaptation.
You can derive your own class from wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override
the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability
and perform the adaptation.
You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation
in a class derived from wxDialog.
You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation
in a class derived from wxDialog.
@subsection overview_dialog_autoscrolling_fail Situations where automatic scrolling adaptation may fail
@subsection overview_dialog_autoscrolling_fail Situations where automatic scrolling adaptation may fail
Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof,
and may fail in the following situations:
Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof,
and may fail in the following situations:
@li The dialog doesn't use sizers.
@li The dialog implementation makes assumptions about the window hierarchy,
for example getting the parent of a control and casting to the dialog class.
@li The dialog does custom painting and/or event handling not handled by the scrolled window.
If this problem can be solved globally, you can derive a new adapter class from
wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return
an instance of your own class.
@li The dialog has unusual layout, for example a vertical sizer containing a mixture of
standard buttons and other controls.
@li The dialog makes assumptions about the sizer hierarchy, for example to show or hide
children of the top-level sizer. However, the original sizer hierarchy will still hold
until Show or ShowModal is called.
@li The dialog doesn't use sizers.
@li The dialog implementation makes assumptions about the window hierarchy,
for example getting the parent of a control and casting to the dialog class.
@li The dialog does custom painting and/or event handling not handled by the scrolled window.
If this problem can be solved globally, you can derive a new adapter class from
wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return
an instance of your own class.
@li The dialog has unusual layout, for example a vertical sizer containing a mixture of
standard buttons and other controls.
@li The dialog makes assumptions about the sizer hierarchy, for example to show or hide
children of the top-level sizer. However, the original sizer hierarchy will still hold
until Show or ShowModal is called.
You can help make sure that your dialogs will continue to function after adaptation by:
You can help make sure that your dialogs will continue to function after adaptation by:
@li avoiding the above situations and assumptions;
@li using wxStdDialogButtonSizer;
@li only making assumptions about hierarchy immediately after the dialog is created;
@li using an intermediate sizer under the main sizer, a @false top-level sizer that
can be relied on to exist for the purposes of manipulating child sizers and windows;
@li overriding wxDialog::GetContentWindow to return a book control if your dialog implements
pages: wxWidgets will then only make the pages scrollable.
@li avoiding the above situations and assumptions;
@li using wxStdDialogButtonSizer;
@li only making assumptions about hierarchy immediately after the dialog is created;
@li using an intermediate sizer under the main sizer, a @false top-level sizer that
can be relied on to exist for the purposes of manipulating child sizers and windows;
@li overriding wxDialog::GetContentWindow to return a book control if your dialog implements
pages: wxWidgets will then only make the pages scrollable.
@subsection overview_dialog_propertysheet wxPropertySheetDialog and wxWizard
@subsection overview_dialog_propertysheet wxPropertySheetDialog and wxWizard
Adaptation for wxPropertySheetDialog is always done by simply making the pages
scrollable, since wxDialog::GetContentWindow returns the dialog's book control and
this is handled by the standard layout adapter.
Adaptation for wxPropertySheetDialog is always done by simply making the pages
scrollable, since wxDialog::GetContentWindow returns the dialog's book control and
this is handled by the standard layout adapter.
wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather
than the global adapter: again, only the wizard pages are made scrollable.
wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather
than the global adapter: again, only the wizard pages are made scrollable.
*/

498
docs/doxygen/overviews/docview.h
View File

@@ -8,325 +8,325 @@
/**
@page overview_docview Document/View Framework
Classes: wxDocument, wxView, wxDocTemplate, wxDocManager, wxDocParentFrame,
wxDocChildFrame, wxDocMDIParentFrame, wxDocMDIChildFrame,
wxCommand, wxCommandProcessor
The document/view framework is found in most application frameworks, because it
can dramatically simplify the code required to build many kinds of application.
The idea is that you can model your application primarily in terms of @e documents to store data
and provide interface-independent operations upon it, and @e views to visualise and manipulate
the data. Documents know how to do input and output given stream objects, and views are responsible
for taking input from physical windows and performing the manipulation on the document data.
If a document's data changes, all views should be updated to reflect the change.
The framework can provide many user-interface elements based on this model.
Once you have defined your own classes and the relationships between them, the framework
takes care of popping up file selectors, opening and closing files, asking the user to save
modifications, routing menu commands to appropriate (possibly default) code, even
some default print/preview functionality and support for command undo/redo.
The framework is highly modular, allowing overriding and replacement of functionality
and objects to achieve more than the default behaviour.
These are the overall steps involved in creating an application based on the
document/view framework:
@li Define your own document and view classes, overriding a minimal set of
member functions e.g. for input/output, drawing and initialization.
@li Define any subwindows (such as a scrolled window) that are needed for the view(s).
You may need to route some events to views or documents, for example OnPaint needs
to be routed to wxView::OnDraw.
@li Decide what style of interface you will use: Microsoft's MDI (multiple
document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
for each document), or single-window (one document open at a time, as in Windows Write).
@li Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
you initialize a view. Create menus using standard menu ids (such as wxID_OPEN, wxID_PRINT).
@li Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
as many wxDocTemplate instances as necessary to define relationships between documents and
views. For a simple application, there will be just one wxDocTemplate.
If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand
and use wxCommandProcessor::Submit instead of directly executing code. The framework will
take care of calling Undo and Do functions as appropriate, so long as the wxID_UNDO and
wxID_REDO menu items are defined in the view menu.
Here are a few examples of the tailoring you can do to go beyond the default framework
behaviour:
@page overview_docview Document/View Framework
Classes: wxDocument, wxView, wxDocTemplate, wxDocManager, wxDocParentFrame,
wxDocChildFrame, wxDocMDIParentFrame, wxDocMDIChildFrame,
wxCommand, wxCommandProcessor
The document/view framework is found in most application frameworks, because it
can dramatically simplify the code required to build many kinds of application.
The idea is that you can model your application primarily in terms of @e documents to store data
and provide interface-independent operations upon it, and @e views to visualise and manipulate
the data. Documents know how to do input and output given stream objects, and views are responsible
for taking input from physical windows and performing the manipulation on the document data.
If a document's data changes, all views should be updated to reflect the change.
The framework can provide many user-interface elements based on this model.
Once you have defined your own classes and the relationships between them, the framework
takes care of popping up file selectors, opening and closing files, asking the user to save
modifications, routing menu commands to appropriate (possibly default) code, even
some default print/preview functionality and support for command undo/redo.
The framework is highly modular, allowing overriding and replacement of functionality
and objects to achieve more than the default behaviour.
These are the overall steps involved in creating an application based on the
document/view framework:
@li Define your own document and view classes, overriding a minimal set of
member functions e.g. for input/output, drawing and initialization.
@li Define any subwindows (such as a scrolled window) that are needed for the view(s).
You may need to route some events to views or documents, for example OnPaint needs
to be routed to wxView::OnDraw.
@li Decide what style of interface you will use: Microsoft's MDI (multiple
document child frames surrounded by an overall frame), SDI (a separate, unconstrained frame
for each document), or single-window (one document open at a time, as in Windows Write).
@li Use the appropriate wxDocParentFrame and wxDocChildFrame classes. Construct an instance
of wxDocParentFrame in your wxApp::OnInit, and a wxDocChildFrame (if not single-window) when
you initialize a view. Create menus using standard menu ids (such as wxID_OPEN, wxID_PRINT).
@li Construct a single wxDocManager instance at the beginning of your wxApp::OnInit, and then
as many wxDocTemplate instances as necessary to define relationships between documents and
views. For a simple application, there will be just one wxDocTemplate.
If you wish to implement Undo/Redo, you need to derive your own class(es) from wxCommand
and use wxCommandProcessor::Submit instead of directly executing code. The framework will
take care of calling Undo and Do functions as appropriate, so long as the wxID_UNDO and
wxID_REDO menu items are defined in the view menu.
Here are a few examples of the tailoring you can do to go beyond the default framework
behaviour:
@li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
or a command history editor.
@li Override wxView::OnCreatePrintout to create an instance of a derived wxPrintout
class, to provide multi-page document facilities.
@li Override wxDocManager::SelectDocumentPath to provide a different file selector.
@li Limit the maximum number of open documents and the maximum number of undo commands.
@li Override wxDocument::OnCreateCommandProcessor to define a different Do/Undo strategy,
or a command history editor.
@li Override wxView::OnCreatePrintout to create an instance of a derived wxPrintout
class, to provide multi-page document facilities.
@li Override wxDocManager::SelectDocumentPath to provide a different file selector.
@li Limit the maximum number of open documents and the maximum number of undo commands.
Note that to activate framework functionality, you need to use some or all of
the wxWidgets @ref overview_docview_predefid in your menus.
Note that to activate framework functionality, you need to use some or all of
the wxWidgets @ref overview_docview_predefid in your menus.
@beginWxPerlOnly
The document/view framework is available in wxPerl. To use it,
you will need the following statements in your application code:
@beginWxPerlOnly
The document/view framework is available in wxPerl. To use it,
you will need the following statements in your application code:
@code
use Wx::DocView;
use Wx ':docview'; # import constants (optional)
@endcode
@endWxPerlOnly
@li @ref overview_docview_wxdoc
@li @ref overview_docview_wxview
@li @ref overview_docview_wxdoctemplate
@li @ref overview_docview_wxdocmanager
@li @ref overview_docview_wxcommand
@li @ref overview_docview_wxcommandproc
@li @ref overview_docview_filehistory
@li @ref overview_docview_predefid
<hr>
@code
use Wx::DocView;
use Wx ':docview'; # import constants (optional)
@endcode
@endWxPerlOnly
@li @ref overview_docview_wxdoc
@li @ref overview_docview_wxview
@li @ref overview_docview_wxdoctemplate
@li @ref overview_docview_wxdocmanager
@li @ref overview_docview_wxcommand
@li @ref overview_docview_wxcommandproc
@li @ref overview_docview_filehistory
@li @ref overview_docview_predefid
<hr>
@section overview_docview_wxdoc wxDocument overview
Class: wxDocument
The wxDocument class can be used to model an application's file-based
data. It is part of the document/view framework supported by wxWidgets,
and cooperates with the wxView, wxDocTemplate and wxDocManager classes.
Using this framework can save a lot of routine user-interface programming,
since a range of menu commands -- such as open, save, save as -- are supported
automatically.
The programmer just needs to define a minimal set of classes and member functions
for the framework to call when necessary. Data, and the means to view and edit
the data, are explicitly separated out in this model, and the concept of multiple
@e views onto the same data is supported.
@section overview_docview_wxdoc wxDocument overview
Class: wxDocument
The wxDocument class can be used to model an application's file-based
data. It is part of the document/view framework supported by wxWidgets,
and cooperates with the wxView, wxDocTemplate and wxDocManager classes.
Using this framework can save a lot of routine user-interface programming,
since a range of menu commands -- such as open, save, save as -- are supported
automatically.
The programmer just needs to define a minimal set of classes and member functions
for the framework to call when necessary. Data, and the means to view and edit
the data, are explicitly separated out in this model, and the concept of multiple
@e views onto the same data is supported.
Note that the document/view model will suit many but not all styles of application.
For example, it would be overkill for a simple file conversion utility, where there
may be no call for @e views on @e documents or the ability to open, edit and save
files. But probably the majority of applications are document-based.
Note that the document/view model will suit many but not all styles of application.
For example, it would be overkill for a simple file conversion utility, where there
may be no call for @e views on @e documents or the ability to open, edit and save
files. But probably the majority of applications are document-based.
See the example application in @c samples/docview.
To use the abstract wxDocument class, you need to derive a new class and override
at least the member functions SaveObject and LoadObject. SaveObject and
LoadObject will be called by the framework when the document needs to be saved
or loaded.
See the example application in @c samples/docview.
To use the abstract wxDocument class, you need to derive a new class and override
at least the member functions SaveObject and LoadObject. SaveObject and
LoadObject will be called by the framework when the document needs to be saved
or loaded.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create document objects on demand. When you create
a wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create document objects on demand. When you create
a wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourDocumentClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
to return an instance of the appropriate class.
If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
to return an instance of the appropriate class.
@section overview_docview_wxview wxView overview
@section overview_docview_wxview wxView overview
Class: wxView
Class: wxView
The wxView class can be used to model the viewing and editing component of
an application's file-based data. It is part of the document/view framework
supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
and wxDocManager classes.
The wxView class can be used to model the viewing and editing component of
an application's file-based data. It is part of the document/view framework
supported by wxWidgets, and cooperates with the wxDocument, wxDocTemplate
and wxDocManager classes.
See the example application in @c samples/docview.
See the example application in @c samples/docview.
To use the abstract wxView class, you need to derive a new class and override
at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably
want to respond to menu commands from the frame containing the view.
To use the abstract wxView class, you need to derive a new class and override
at least the member functions OnCreate, OnDraw, OnUpdate and OnClose. You will probably
want to respond to menu commands from the frame containing the view.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create view objects on demand. When you create
a wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
Use the macros DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS in order
to allow the framework to create view objects on demand. When you create
a wxDocTemplate object on application initialization, you
should pass CLASSINFO(YourViewClass) to the wxDocTemplate constructor
so that it knows how to create an instance of this class.
If you do not wish to use the wxWidgets method of creating view
objects dynamically, you must override wxDocTemplate::CreateView
to return an instance of the appropriate class.
If you do not wish to use the wxWidgets method of creating view
objects dynamically, you must override wxDocTemplate::CreateView
to return an instance of the appropriate class.
@section overview_docview_wxdoctemplate wxDocTemplate overview
@section overview_docview_wxdoctemplate wxDocTemplate overview
Class: wxDocTemplate
Class: wxDocTemplate
The wxDocTemplate class is used to model the relationship between a
document class and a view class. The application creates a document
template object for each document/view pair. The list of document
templates managed by the wxDocManager instance is used to create
documents and views. Each document template knows what file filters
and default extension are appropriate for a document/view combination,
and how to create a document or view.
The wxDocTemplate class is used to model the relationship between a
document class and a view class. The application creates a document
template object for each document/view pair. The list of document
templates managed by the wxDocManager instance is used to create
documents and views. Each document template knows what file filters
and default extension are appropriate for a document/view combination,
and how to create a document or view.
For example, you might write a small doodling application that can load
and save lists of line segments. If you had two views of the data -- graphical,
and a list of the segments -- then you would create one document class DoodleDocument,
and two view classes (DoodleGraphicView and DoodleListView). You would also
need two document templates, one for the graphical view and another for the
list view. You would pass the same document class and default file extension to both
document templates, but each would be passed a different view class. When
the user clicks on the Open menu item, the file selector is displayed
with a list of possible file filters -- one for each wxDocTemplate. Selecting
the filter selects the wxDocTemplate, and when a file is selected, that template
will be used for creating a document and view.
For example, you might write a small doodling application that can load
and save lists of line segments. If you had two views of the data -- graphical,
and a list of the segments -- then you would create one document class DoodleDocument,
and two view classes (DoodleGraphicView and DoodleListView). You would also
need two document templates, one for the graphical view and another for the
list view. You would pass the same document class and default file extension to both
document templates, but each would be passed a different view class. When
the user clicks on the Open menu item, the file selector is displayed
with a list of possible file filters -- one for each wxDocTemplate. Selecting
the filter selects the wxDocTemplate, and when a file is selected, that template
will be used for creating a document and view.
For the case where an application has one document type and one view type,
a single document template is constructed, and dialogs will be appropriately
simplified.
For the case where an application has one document type and one view type,
a single document template is constructed, and dialogs will be appropriately
simplified.
wxDocTemplate is part of the document/view framework supported by wxWidgets,
and cooperates with the wxView, wxDocument and wxDocManager classes.
wxDocTemplate is part of the document/view framework supported by wxWidgets,
and cooperates with the wxView, wxDocument and wxDocManager classes.
See the example application in @c samples/docview.
See the example application in @c samples/docview.
To use the wxDocTemplate class, you do not need to derive a new class.
Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass)
and CLASSINFO(YourViewClass) to allow dynamic instance creation.
To use the wxDocTemplate class, you do not need to derive a new class.
Just pass relevant information to the constructor including CLASSINFO(YourDocumentClass)
and CLASSINFO(YourViewClass) to allow dynamic instance creation.
If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
and wxDocTemplate::CreateView to return instances of the appropriate class.
If you do not wish to use the wxWidgets method of creating document
objects dynamically, you must override wxDocTemplate::CreateDocument
and wxDocTemplate::CreateView to return instances of the appropriate class.
@note The document template has nothing to do with the C++ template construct.
@note The document template has nothing to do with the C++ template construct.
@section overview_docview_wxdocmanager wxDocManager overview
@section overview_docview_wxdocmanager wxDocManager overview
Class: wxDocManager
Class: wxDocManager
The wxDocManager class is part of the document/view framework supported by wxWidgets,
and cooperates with the wxView, wxDocument and wxDocTemplate classes.
The wxDocManager class is part of the document/view framework supported by wxWidgets,
and cooperates with the wxView, wxDocument and wxDocTemplate classes.
A wxDocManager instance coordinates documents, views and document templates.
It keeps a list of document and template instances, and much functionality is routed
through this object, such as providing selection and file dialogs.
The application can use this class 'as is' or derive a class and override some members
to extend or change the functionality.
A wxDocManager instance coordinates documents, views and document templates.
It keeps a list of document and template instances, and much functionality is routed
through this object, such as providing selection and file dialogs.
The application can use this class 'as is' or derive a class and override some members
to extend or change the functionality.
Create an instance of this class near the beginning of your application initialization,
before any documents, views or templates are manipulated.
Create an instance of this class near the beginning of your application initialization,
before any documents, views or templates are manipulated.
There may be multiple wxDocManager instances in an application.
See the example application in @c samples/docview.
There may be multiple wxDocManager instances in an application.
See the example application in @c samples/docview.
@section overview_docview_wxcommand wxCommand overview
@section overview_docview_wxcommand wxCommand overview
Classes: wxCommand, wxCommandProcessor
Classes: wxCommand, wxCommandProcessor
wxCommand is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing
a toolbar button or any other means provided by the application to
change the data or view.
wxCommand is a base class for modelling an application command,
which is an action usually performed by selecting a menu item, pressing
a toolbar button or any other means provided by the application to
change the data or view.
Instead of the application functionality being scattered around
switch statements and functions in a way that may be hard to
read and maintain, the functionality for a command is explicitly represented
as an object which can be manipulated by a framework or application.
Instead of the application functionality being scattered around
switch statements and functions in a way that may be hard to
read and maintain, the functionality for a command is explicitly represented
as an object which can be manipulated by a framework or application.
When a user interface event occurs, the application @e submits a command
to a wxCommandProcessor object to execute and store.
When a user interface event occurs, the application @e submits a command
to a wxCommandProcessor object to execute and store.
The wxWidgets document/view framework handles Undo and Redo by use of
wxCommand and wxCommandProcessor objects. You might find further uses
for wxCommand, such as implementing a macro facility that stores, loads
and replays commands.
The wxWidgets document/view framework handles Undo and Redo by use of
wxCommand and wxCommandProcessor objects. You might find further uses
for wxCommand, such as implementing a macro facility that stores, loads
and replays commands.
An application can derive a new class for every command, or, more likely, use
one class parameterized with an integer or string command identifier.
An application can derive a new class for every command, or, more likely, use
one class parameterized with an integer or string command identifier.
@section overview_docview_wxcommandproc wxCommandProcessor overview
@section overview_docview_wxcommandproc wxCommandProcessor overview
Classes: wxCommandProcessor, wxCommand
Classes: wxCommandProcessor, wxCommand
wxCommandProcessor is a class that maintains a history of wxCommand
instances, with undo/redo functionality built-in. Derive a new class from this
if you want different behaviour.
wxCommandProcessor is a class that maintains a history of wxCommand
instances, with undo/redo functionality built-in. Derive a new class from this
if you want different behaviour.
@section overview_docview_filehistory wxFileHistory overview
@section overview_docview_filehistory wxFileHistory overview
Classes: wxFileHistory, wxDocManager
Classes: wxFileHistory, wxDocManager
wxFileHistory encapsulates functionality to record the last few files visited, and
to allow the user to quickly load these files using the list appended to the File menu.
Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish
to derive from it to allow different behaviour, such as popping up a scrolling
list of files.
wxFileHistory encapsulates functionality to record the last few files visited, and
to allow the user to quickly load these files using the list appended to the File menu.
Although wxFileHistory is used by wxDocManager, it can be used independently. You may wish
to derive from it to allow different behaviour, such as popping up a scrolling
list of files.
By calling wxFileHistory::UseMenu() you can associate a file menu with the file history.
The menu will then be used for appending filenames that are added to the history.
By calling wxFileHistory::UseMenu() you can associate a file menu with the file history.
The menu will then be used for appending filenames that are added to the history.
Please notice that currently if the history already contained filenames when UseMenu()
is called (e.g. when initializing a second MDI child frame), the menu is not automatically
initialized with the existing filenames in the history and so you need to call
wxFileHistory::AddFilesToMenu() after UseMenu() explicitly in order to initialize the menu with
the existing list of MRU files (otherwise an assertion failure is raised in debug builds).
Please notice that currently if the history already contained filenames when UseMenu()
is called (e.g. when initializing a second MDI child frame), the menu is not automatically
initialized with the existing filenames in the history and so you need to call
wxFileHistory::AddFilesToMenu() after UseMenu() explicitly in order to initialize the menu with
the existing list of MRU files (otherwise an assertion failure is raised in debug builds).
The filenames are appended using menu identifiers in the range @c wxID_FILE1 to @c wxID_FILE9.
The filenames are appended using menu identifiers in the range @c wxID_FILE1 to @c wxID_FILE9.
In order to respond to a file load command from one of these identifiers,
you need to handle them using an event handler, for example:
In order to respond to a file load command from one of these identifiers,
you need to handle them using an event handler, for example:
@code
BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
EVT_MENU_RANGE(wxID_FILE1, wxID_FILE9, wxDocParentFrame::OnMRUFile)
END_EVENT_TABLE()
@code
BEGIN_EVENT_TABLE(wxDocParentFrame, wxFrame)
EVT_MENU(wxID_EXIT, wxDocParentFrame::OnExit)
EVT_MENU_RANGE(wxID_FILE1, wxID_FILE9, wxDocParentFrame::OnMRUFile)
END_EVENT_TABLE()
void wxDocParentFrame::OnExit(wxCommandEvent& WXUNUSED(event))
{
Close();
}
void wxDocParentFrame::OnExit(wxCommandEvent& WXUNUSED(event))
{
Close();
}
void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
{
wxString f(m_docManager->GetHistoryFile(event.GetId() - wxID_FILE1));
if (!f.empty())
(void)m_docManager-CreateDocument(f, wxDOC_SILENT);
}
@endcode
void wxDocParentFrame::OnMRUFile(wxCommandEvent& event)
{
wxString f(m_docManager->GetHistoryFile(event.GetId() - wxID_FILE1));
if (!f.empty())
(void)m_docManager-CreateDocument(f, wxDOC_SILENT);
}
@endcode
@section overview_docview_predefid wxWidgets predefined command identifiers
@section overview_docview_predefid wxWidgets predefined command identifiers
To allow communication between the application's menus and the
document/view framework, several command identifiers are predefined for you
to use in menus.
To allow communication between the application's menus and the
document/view framework, several command identifiers are predefined for you
to use in menus.
@verbatim
wxID_OPEN (5000)
wxID_CLOSE (5001)
wxID_NEW (5002)
wxID_SAVE (5003)
wxID_SAVEAS (5004)
wxID_REVERT (5005)
wxID_EXIT (5006)
wxID_UNDO (5007)
wxID_REDO (5008)
wxID_HELP (5009)
wxID_PRINT (5010)
wxID_PRINT_SETUP (5011)
wxID_PREVIEW (5012)
@endverbatim
@verbatim
wxID_OPEN (5000)
wxID_CLOSE (5001)
wxID_NEW (5002)
wxID_SAVE (5003)
wxID_SAVEAS (5004)
wxID_REVERT (5005)
wxID_EXIT (5006)
wxID_UNDO (5007)
wxID_REDO (5008)
wxID_HELP (5009)
wxID_PRINT (5010)
wxID_PRINT_SETUP (5011)
wxID_PREVIEW (5012)
@endverbatim
*/

48
docs/doxygen/overviews/envvars.h
View File

@@ -8,32 +8,32 @@
/**
@page overview_envvars Environment Variables
@page overview_envvars Environment Variables
This section describes all environment variables that affect execution of
wxWidgets programs.
This section describes all environment variables that affect execution of
wxWidgets programs.
@beginDefList
@itemdef{WXTRACE,
(Debug build only.)
This variable can be set to a comma-separated list of trace masks used in
wxLogTrace calls; wxLog::AddTraceMask is called for every mask
in the list during wxWidgets initialization.}
@itemdef{WXPREFIX,
(Unix only.)
Overrides installation prefix. Normally, the prefix
is hard-coded and is the same as the value passed to @c configure via
the @c --prefix switch when compiling the library (typically
@c /usr/local or @c /usr). You can set WXPREFIX if you are for example
distributing a binary version of an application and you don't know in advance
where it will be installed.}
@itemdef{WXMODE,
(wxMGL only.)
Sets MGL video mode. The value must be in form
@e widthx@e height-@e depth. The default is @c 640x480-16.}
@itemdef{WXSTDERR,
(wxMGL only.)
Redirects stderr output to a file.}
@beginDefList
@itemdef{WXTRACE,
(Debug build only.)
This variable can be set to a comma-separated list of trace masks used in
wxLogTrace calls; wxLog::AddTraceMask is called for every mask
in the list during wxWidgets initialization.}
@itemdef{WXPREFIX,
(Unix only.)
Overrides installation prefix. Normally, the prefix
is hard-coded and is the same as the value passed to @c configure via
the @c --prefix switch when compiling the library (typically
@c /usr/local or @c /usr). You can set WXPREFIX if you are for example
distributing a binary version of an application and you don't know in advance
where it will be installed.}
@itemdef{WXMODE,
(wxMGL only.)
Sets MGL video mode. The value must be in form
@e widthx@e height-@e depth. The default is @c 640x480-16.}
@itemdef{WXSTDERR,
(wxMGL only.)
Redirects stderr output to a file.}
*/

106
docs/doxygen/overviews/exceptions.h
View File

@@ -8,75 +8,75 @@
/**
@page overview_exceptions C++ Exceptions
@page overview_exceptions C++ Exceptions
@li @ref overview_exceptions_introduction
@li @ref overview_exceptions_strategies
@li @ref overview_exceptions_tech
@li @ref overview_exceptions_introduction
@li @ref overview_exceptions_strategies
@li @ref overview_exceptions_tech
<hr>
<hr>
@section overview_exceptions_introduction Introduction
@section overview_exceptions_introduction Introduction
wxWidgets had been started long before the exceptions were introduced in C++ so
it is not very surprising that it is not built around using them as some more
modern C++ libraries are. For instance, the library doesn't throw exceptions to
signal about the errors. Moreover, up to (and including) the version 2.4 of
wxWidgets, even using the exceptions in the user code was dangerous because the
library code wasn't exception-safe and so an exception propagating through it
could result in memory and/or resource leaks, and also not very convenient.
wxWidgets had been started long before the exceptions were introduced in C++ so
it is not very surprising that it is not built around using them as some more
modern C++ libraries are. For instance, the library doesn't throw exceptions to
signal about the errors. Moreover, up to (and including) the version 2.4 of
wxWidgets, even using the exceptions in the user code was dangerous because the
library code wasn't exception-safe and so an exception propagating through it
could result in memory and/or resource leaks, and also not very convenient.
wxWidgets is exception-friendly.
It still doesn't use the exceptions by itself but it should be now safe to use the
exceptions in the user code and the library tries to help you with this. Please
note that making the library exception-safe is still work in progress.
wxWidgets is exception-friendly.
It still doesn't use the exceptions by itself but it should be now safe to use the
exceptions in the user code and the library tries to help you with this. Please
note that making the library exception-safe is still work in progress.
@section overview_exceptions_strategies Strategies for exceptions handling
@section overview_exceptions_strategies Strategies for exceptions handling
There are several choice for using the exceptions in wxWidgets programs. First
of all, you may not use them at all. As stated above, the library doesn't throw
any exceptions by itself and so you don't have to worry about exceptions at all
unless your own code throws them. This is, of course, the simplest solution but
may be not the best one to deal with all possible errors.
There are several choice for using the exceptions in wxWidgets programs. First
of all, you may not use them at all. As stated above, the library doesn't throw
any exceptions by itself and so you don't have to worry about exceptions at all
unless your own code throws them. This is, of course, the simplest solution but
may be not the best one to deal with all possible errors.
Another strategy is to use exceptions only to signal truly fatal errors. In
this case you probably don't expect to recover from them and the default
behaviour -- to simply terminate the program -- may be appropriate. If it is
not, you may override wxApp::OnUnhandledException()
in your wxApp-derived class to perform any clean up tasks. Note, however, that
any information about the exact exception type is lost when this function is
called, so if you need you should override wxApp::OnRun() and
add a try/catch clause around the call of the base class version. This would
allow you to catch any exceptions generated during the execution of the main
event loop. To deal with the exceptions which may arise during the program
startup and/or shutdown you should insert try/catch clauses in
wxApp::OnInit() and/or wxApp::OnExit() as well.
Another strategy is to use exceptions only to signal truly fatal errors. In
this case you probably don't expect to recover from them and the default
behaviour -- to simply terminate the program -- may be appropriate. If it is
not, you may override wxApp::OnUnhandledException()
in your wxApp-derived class to perform any clean up tasks. Note, however, that
any information about the exact exception type is lost when this function is
called, so if you need you should override wxApp::OnRun() and
add a try/catch clause around the call of the base class version. This would
allow you to catch any exceptions generated during the execution of the main
event loop. To deal with the exceptions which may arise during the program
startup and/or shutdown you should insert try/catch clauses in
wxApp::OnInit() and/or wxApp::OnExit() as well.
Finally, you may also want to continue running even when certain exceptions
occur. If all of your exceptions may happen only in the event handlers of a
single class (or only in the classes derived from it), you may centralize your
exception handling code in wxApp::ProcessEvent
method of this class. If this is impractical, you may also consider overriding
the wxApp::HandleEvent() which allows you to handle
all the exceptions thrown by any event handler.
Finally, you may also want to continue running even when certain exceptions
occur. If all of your exceptions may happen only in the event handlers of a
single class (or only in the classes derived from it), you may centralize your
exception handling code in wxApp::ProcessEvent
method of this class. If this is impractical, you may also consider overriding
the wxApp::HandleEvent() which allows you to handle
all the exceptions thrown by any event handler.
@section overview_exceptions_tech Technicalities
@section overview_exceptions_tech Technicalities
To use any kind of exception support in the library you need to build it
with @c wxUSE_EXCEPTIONS set to 1. This should be the case by default but
if it isn't, you should edit the @c include/wx/msw/setup.h file under
Windows or run @c configure with @c --enable-exceptions argument
under Unix.
To use any kind of exception support in the library you need to build it
with @c wxUSE_EXCEPTIONS set to 1. This should be the case by default but
if it isn't, you should edit the @c include/wx/msw/setup.h file under
Windows or run @c configure with @c --enable-exceptions argument
under Unix.
On the other hand, if you do not plan to use exceptions, setting this
flag to 0 or using @c --disable-exceptions could result in a leaner and
slightly faster library.
On the other hand, if you do not plan to use exceptions, setting this
flag to 0 or using @c --disable-exceptions could result in a leaner and
slightly faster library.
As for any other library feature, there is a sample (@c except)
showing how to use it. Please look at its sources for further information.
As for any other library feature, there is a sample (@c except)
showing how to use it. Please look at its sources for further information.
*/

44
docs/doxygen/overviews/file.h
View File

@@ -8,35 +8,35 @@
/**
@page overview_file File Classes and Functions
@page overview_file File Classes and Functions
Classes: wxFile, wxDir, wxTempFile, wxTextFile
Classes: wxFile, wxDir, wxTempFile, wxTextFile
Functions: see @ref page_func_cat_file.
Functions: see @ref page_func_cat_file.
wxWidgets provides some functions and classes to facilitate working with files.
As usual, the accent is put on cross-platform features which explains, for
example, the wxTextFile class which may be used to convert
between different types of text files (DOS/Unix/Mac).
wxWidgets provides some functions and classes to facilitate working with files.
As usual, the accent is put on cross-platform features which explains, for
example, the wxTextFile class which may be used to convert
between different types of text files (DOS/Unix/Mac).
wxFile may be used for low-level IO. It contains all the usual functions to work
with files (opening/closing, reading/writing, seeking, and so on) but compared with
using standard C functions, has error checking (in case of an error a message
is logged using wxLog facilities) and closes the file
automatically in the destructor which may be quite convenient.
wxFile may be used for low-level IO. It contains all the usual functions to work
with files (opening/closing, reading/writing, seeking, and so on) but compared with
using standard C functions, has error checking (in case of an error a message
is logged using wxLog facilities) and closes the file
automatically in the destructor which may be quite convenient.
wxTempFile is a very small file designed to make replacing the files contents
safer - see its documentation for more details.
wxTempFile is a very small file designed to make replacing the files contents
safer - see its documentation for more details.
wxTextFile is a general purpose class for working with small text files on line
by line basis. It is especially well suited for working with configuration files
and program source files. It can be also used to work with files with "non
native" line termination characters and write them as "native" files if needed
(in fact, the files may be written in any format).
wxTextFile is a general purpose class for working with small text files on line
by line basis. It is especially well suited for working with configuration files
and program source files. It can be also used to work with files with "non
native" line termination characters and write them as "native" files if needed
(in fact, the files may be written in any format).
wxDir is a helper class for enumerating the files or subdirectories of a
directory. It may be used to enumerate all files, only files satisfying the
given template mask or only non-hidden files.
wxDir is a helper class for enumerating the files or subdirectories of a
directory. It may be used to enumerate all files, only files satisfying the
given template mask or only non-hidden files.
*/

150
docs/doxygen/overviews/filesystem.h
View File

@@ -8,109 +8,109 @@
/**
@page overview_fs wxFileSystem Overview
@page overview_fs wxFileSystem Overview
The wxHTML library uses a @b virtual file systems mechanism
similar to the one used in Midnight Commander, Dos Navigator,
FAR or almost any modern file manager. It allows the user to access
data stored in archives as if they were ordinary files. On-the-fly
generated files that exist only in memory are also supported.
The wxHTML library uses a @b virtual file systems mechanism
similar to the one used in Midnight Commander, Dos Navigator,
FAR or almost any modern file manager. It allows the user to access
data stored in archives as if they were ordinary files. On-the-fly
generated files that exist only in memory are also supported.
@li @ref overview_fs_classes
@li @ref overview_fs_locations
@li @ref overview_fs_combined
@li @ref overview_fs_wxhtmlfs
@li @ref overview_fs_init
@li @ref overview_fs_classes
@li @ref overview_fs_locations
@li @ref overview_fs_combined
@li @ref overview_fs_wxhtmlfs
@li @ref overview_fs_init
<hr>
<hr>
@section overview_fs_classes Classes
@section overview_fs_classes Classes
Three classes are used in order to provide virtual file systems mechanism:
Three classes are used in order to provide virtual file systems mechanism:
@li The wxFSFile class provides information
about opened file (name, input stream, mime type and anchor).
@li The wxFileSystem class is the interface.
Its main methods are ChangePathTo() and OpenFile(). This class
is most often used by the end user.
@li The wxFileSystemHandler is the core
of virtual file systems mechanism. You can derive your own handler and pass
it to the VFS mechanism. You can derive your own handler and pass it to
wxFileSystem's AddHandler() method. In the new handler you only need to
override the OpenFile() and CanOpen() methods.
@li The wxFSFile class provides information
about opened file (name, input stream, mime type and anchor).
@li The wxFileSystem class is the interface.
Its main methods are ChangePathTo() and OpenFile(). This class
is most often used by the end user.
@li The wxFileSystemHandler is the core
of virtual file systems mechanism. You can derive your own handler and pass
it to the VFS mechanism. You can derive your own handler and pass it to
wxFileSystem's AddHandler() method. In the new handler you only need to
override the OpenFile() and CanOpen() methods.
@section overview_fs_locations Locations
@section overview_fs_locations Locations
Locations (aka filenames aka addresses) are constructed from four parts:
Locations (aka filenames aka addresses) are constructed from four parts:
@li @b protocol - handler can recognize if it is able to open a
file by checking its protocol. Examples are "http", "file" or "ftp".
@li <b>right location</b> - is the name of file within the protocol.
In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html".
@li @b anchor - an anchor is optional and is usually not present.
In "index.htm#chapter2" the anchor is "chapter2".
@li <b>left location</b> - this is usually an empty string.
It is used by 'local' protocols such as ZIP.
See Combined Protocols paragraph for details.
@li @b protocol - handler can recognize if it is able to open a
file by checking its protocol. Examples are "http", "file" or "ftp".
@li <b>right location</b> - is the name of file within the protocol.
In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html".
@li @b anchor - an anchor is optional and is usually not present.
In "index.htm#chapter2" the anchor is "chapter2".
@li <b>left location</b> - this is usually an empty string.
It is used by 'local' protocols such as ZIP.
See Combined Protocols paragraph for details.
@section overview_fs_combined Combined Protocols
@section overview_fs_combined Combined Protocols
The left location precedes the protocol in the URL string.
The left location precedes the protocol in the URL string.
It is not used by global protocols like HTTP but it becomes handy when nesting
protocols - for example you may want to access files in a ZIP archive:
file:archives/cpp_doc.zip#zip:reference/fopen.htm#syntax
In this example, the protocol is "zip", right location is
"reference/fopen.htm", anchor is "syntax" and left location
is "file:archives/cpp_doc.zip".
It is not used by global protocols like HTTP but it becomes handy when nesting
protocols - for example you may want to access files in a ZIP archive:
file:archives/cpp_doc.zip#zip:reference/fopen.htm#syntax
In this example, the protocol is "zip", right location is
"reference/fopen.htm", anchor is "syntax" and left location
is "file:archives/cpp_doc.zip".
There are @b two protocols used in this example: "zip" and "file".
There are @b two protocols used in this example: "zip" and "file".
@section overview_fs_wxhtmlfs File Systems Included in wxHTML
@section overview_fs_wxhtmlfs File Systems Included in wxHTML
The following virtual file system handlers are part of wxWidgets so far:
The following virtual file system handlers are part of wxWidgets so far:
@li @b wxArchiveFSHandler:
A handler for archives such as zip
and tar. Include file is wx/fs_arc.h. URLs examples:
"archive.zip#zip:filename", "archive.tar.gz#gzip:#tar:filename".
@li @b wxFilterFSHandler:
A handler for compression schemes such
as gzip. Header is wx/fs_filter.h. URLs are in the form, e.g.:
"document.ps.gz#gzip:".
@li @b wxInternetFSHandler:
A handler for accessing documents
via HTTP or FTP protocols. Include file is wx/fs_inet.h.
@li @b wxMemoryFSHandler:
This handler allows you to access
data stored in memory (such as bitmaps) as if they were regular files.
See wxMemoryFSHandler for details.
Include file is wx/fs_mem.h. URL is prefixed with memory:, e.g.
"memory:myfile.htm"
@li @b wxArchiveFSHandler:
A handler for archives such as zip
and tar. Include file is wx/fs_arc.h. URLs examples:
"archive.zip#zip:filename", "archive.tar.gz#gzip:#tar:filename".
@li @b wxFilterFSHandler:
A handler for compression schemes such
as gzip. Header is wx/fs_filter.h. URLs are in the form, e.g.:
"document.ps.gz#gzip:".
@li @b wxInternetFSHandler:
A handler for accessing documents
via HTTP or FTP protocols. Include file is wx/fs_inet.h.
@li @b wxMemoryFSHandler:
This handler allows you to access
data stored in memory (such as bitmaps) as if they were regular files.
See wxMemoryFSHandler for details.
Include file is wx/fs_mem.h. URL is prefixed with memory:, e.g.
"memory:myfile.htm"
In addition, wxFileSystem itself can access local files.
In addition, wxFileSystem itself can access local files.
@section overview_fs_init Initializing file system handlers
@section overview_fs_init Initializing file system handlers
Use wxFileSystem::AddHandler to initialize a handler, for example:
Use wxFileSystem::AddHandler to initialize a handler, for example:
@code
#include <wx/fs_mem.h>
@code
#include <wx/fs_mem.h>
...
...
bool MyApp::OnInit()
{
wxFileSystem::AddHandler(new wxMemoryFSHandler);
...
}
@endcode
bool MyApp::OnInit()
{
wxFileSystem::AddHandler(new wxMemoryFSHandler);
...
}
@endcode
*/

114
docs/doxygen/overviews/font.h
View File

@@ -8,79 +8,79 @@
/**
@page overview_font wxFont Overview
@page overview_font wxFont Overview
Class: wxFont, wxFontDialog
Class: wxFont, wxFontDialog
@li @ref overview_font_intro
@li @ref overview_font_nativeinfo
@li @ref overview_font_intro
@li @ref overview_font_nativeinfo
<hr>
<hr>
@section overview_font_intro Introduction
@section overview_font_intro Introduction
A font is an object which determines the appearance of text, primarily
when drawing text to a window or device context. A font is determined by
the following parameters (not all of them have to be specified, of course):
A font is an object which determines the appearance of text, primarily
when drawing text to a window or device context. A font is determined by
the following parameters (not all of them have to be specified, of course):
@beginDefList
@itemdef{Point size, This is the standard way of referring to text size.}
@itemdef{Family,
Supported families are:
@b wxDEFAULT, @b wxDECORATIVE, @b wxROMAN, @b wxSCRIPT, @b wxSWISS, @b wxMODERN.
@b wxMODERN is a fixed pitch font; the others are either fixed or variable pitch.}
@itemdef{Style, The value can be @b wxNORMAL, @b wxSLANT or @b wxITALIC.}
@itemdef{Weight, The value can be @b wxNORMAL, @b wxLIGHT or @b wxBOLD.}
@itemdef{Underlining, The value can be @true or @false.}
@itemdef{Face name,
An optional string specifying the actual typeface to be used. If @NULL,
a default typeface will chosen based on the family.}
@itemdef{Encoding,
The font encoding (see @b wxFONTENCODING_XXX
constants and the @ref overview_fontencoding for more details)}
@endDefList
@beginDefList
@itemdef{Point size, This is the standard way of referring to text size.}
@itemdef{Family,
Supported families are:
@b wxDEFAULT, @b wxDECORATIVE, @b wxROMAN, @b wxSCRIPT, @b wxSWISS, @b wxMODERN.
@b wxMODERN is a fixed pitch font; the others are either fixed or variable pitch.}
@itemdef{Style, The value can be @b wxNORMAL, @b wxSLANT or @b wxITALIC.}
@itemdef{Weight, The value can be @b wxNORMAL, @b wxLIGHT or @b wxBOLD.}
@itemdef{Underlining, The value can be @true or @false.}
@itemdef{Face name,
An optional string specifying the actual typeface to be used. If @NULL,
a default typeface will chosen based on the family.}
@itemdef{Encoding,
The font encoding (see @b wxFONTENCODING_XXX
constants and the @ref overview_fontencoding for more details)}
@endDefList
Specifying a family, rather than a specific typeface name, ensures a degree of
portability across platforms because a suitable font will be chosen for the
given font family, however it doesn't allow to choose a font precisely as the
parameters above don't suffice, in general, to identify all the available fonts
and this is where using the native font descriptions may be helpful - see
below.
Specifying a family, rather than a specific typeface name, ensures a degree of
portability across platforms because a suitable font will be chosen for the
given font family, however it doesn't allow to choose a font precisely as the
parameters above don't suffice, in general, to identify all the available fonts
and this is where using the native font descriptions may be helpful - see
below.
Under Windows, the face name can be one of the installed fonts on the user's
system. Since the choice of fonts differs from system to system, either choose
standard Windows fonts, or if allowing the user to specify a face name, store
the family name with any file that might be transported to a different Windows
machine or other platform.
Under Windows, the face name can be one of the installed fonts on the user's
system. Since the choice of fonts differs from system to system, either choose
standard Windows fonts, or if allowing the user to specify a face name, store
the family name with any file that might be transported to a different Windows
machine or other platform.
@note There is currently a difference between the appearance
of fonts on the two platforms, if the mapping mode is anything other than
wxMM_TEXT. Under X, font size is always specified in points. Under MS
Windows, the unit for text is points but the text is scaled according to the
current mapping mode. However, user scaling on a device context will also
scale fonts under both environments.
@note There is currently a difference between the appearance
of fonts on the two platforms, if the mapping mode is anything other than
wxMM_TEXT. Under X, font size is always specified in points. Under MS
Windows, the unit for text is points but the text is scaled according to the
current mapping mode. However, user scaling on a device context will also
scale fonts under both environments.
@section overview_font_nativeinfo Native font information
@section overview_font_nativeinfo Native font information
An alternative way of choosing fonts is to use the native font description.
This is the only acceptable solution if the user is allowed to choose the font
using the wxFontDialog because the selected font cannot
be described using only the family name and so, if only family name is stored
permanently, the user would almost surely see a different font in the program
later.
An alternative way of choosing fonts is to use the native font description.
This is the only acceptable solution if the user is allowed to choose the font
using the wxFontDialog because the selected font cannot
be described using only the family name and so, if only family name is stored
permanently, the user would almost surely see a different font in the program
later.
Instead, you should store the value returned by wxFont::GetNativeFontInfoDesc and pass
it to wxFont::SetNativeFontInfo later to recreate exactly the same font.
Instead, you should store the value returned by wxFont::GetNativeFontInfoDesc and pass
it to wxFont::SetNativeFontInfo later to recreate exactly the same font.
Note that the contents of this string depends on the platform and shouldn't be
used for any other purpose (in particular, it is not meant to be shown to the
user). Also please note that although the native font information is currently
implemented for Windows and Unix (GTK+ and Motif) ports only, all the methods
are available for all the ports and should be used to make your program work
correctly when they are implemented later.
Note that the contents of this string depends on the platform and shouldn't be
used for any other purpose (in particular, it is not meant to be shown to the
user). Also please note that although the native font information is currently
implemented for Windows and Unix (GTK+ and Motif) ports only, all the methods
are available for all the ports and should be used to make your program work
correctly when they are implemented later.
*/

92
docs/doxygen/overviews/grid.h
View File

@@ -8,82 +8,82 @@
/**
@page overview_grid wxGrid Overview
@page overview_grid wxGrid Overview
Classes: wxGrid
Classes: wxGrid
@li @ref overview_grid_intro
@li @ref overview_grid_simpleexample
@li @ref overview_grid_complexexample
@li @ref overview_grid_classrelations
@li @ref overview_grid_keyboardmouse
@li @ref overview_grid_intro
@li @ref overview_grid_simpleexample
@li @ref overview_grid_complexexample
@li @ref overview_grid_classrelations
@li @ref overview_grid_keyboardmouse
<hr>
<hr>
@section overview_grid_intro Introduction
@section overview_grid_intro Introduction
wxGrid and its related classes are used for displaying and editing tabular data.
wxGrid and its related classes are used for displaying and editing tabular data.
@section overview_grid_simpleexample Getting started: a simple example
@section overview_grid_simpleexample Getting started: a simple example
For simple applications you need only refer to the wxGrid class in your
code. This example shows how you might create a grid in a frame or
dialog constructor and illustrates some of the formatting functions.
For simple applications you need only refer to the wxGrid class in your
code. This example shows how you might create a grid in a frame or
dialog constructor and illustrates some of the formatting functions.
@code
// Create a wxGrid object
@code
// Create a wxGrid object
grid = new wxGrid( this,
grid = new wxGrid( this,
-1,
wxPoint( 0, 0 ),
wxSize( 400, 300 ) );
// Then we call CreateGrid to set the dimensions of the grid
// (100 rows and 10 columns in this example)
grid->CreateGrid( 100, 10 );
// Then we call CreateGrid to set the dimensions of the grid
// (100 rows and 10 columns in this example)
grid->CreateGrid( 100, 10 );
// We can set the sizes of individual rows and columns
// in pixels
grid->SetRowSize( 0, 60 );
grid->SetColSize( 0, 120 );
// We can set the sizes of individual rows and columns
// in pixels
grid->SetRowSize( 0, 60 );
grid->SetColSize( 0, 120 );
// And set grid cell contents as strings
grid->SetCellValue( 0, 0, "wxGrid is good" );
// And set grid cell contents as strings
grid->SetCellValue( 0, 0, "wxGrid is good" );
// We can specify that some cells are read->only
grid->SetCellValue( 0, 3, "This is read->only" );
grid->SetReadOnly( 0, 3 );
// We can specify that some cells are read->only
grid->SetCellValue( 0, 3, "This is read->only" );
grid->SetReadOnly( 0, 3 );
// Colours can be specified for grid cell contents
grid->SetCellValue(3, 3, "green on grey");
grid->SetCellTextColour(3, 3, *wxGREEN);
grid->SetCellBackgroundColour(3, 3, *wxLIGHT_GREY);
// Colours can be specified for grid cell contents
grid->SetCellValue(3, 3, "green on grey");
grid->SetCellTextColour(3, 3, *wxGREEN);
grid->SetCellBackgroundColour(3, 3, *wxLIGHT_GREY);
// We can specify the some cells will store numeric
// values rather than strings. Here we set grid column 5
// to hold floating point values displayed with width of 6
// and precision of 2
grid->SetColFormatFloat(5, 6, 2);
grid->SetCellValue(0, 6, "3.1415");
@endcode
// We can specify the some cells will store numeric
// values rather than strings. Here we set grid column 5
// to hold floating point values displayed with width of 6
// and precision of 2
grid->SetColFormatFloat(5, 6, 2);
grid->SetCellValue(0, 6, "3.1415");
@endcode
@section overview_grid_complexexample A more complex example
@section overview_grid_complexexample A more complex example
Yet to be written
@todo Yet to be written
@section overview_grid_classrelations How the wxGrid classes relate to each other
@section overview_grid_classrelations How the wxGrid classes relate to each other
Yet to be written
@todo Yet to be written
@section overview_grid_keyboardmouse Keyboard and mouse actions
@section overview_grid_keyboardmouse Keyboard and mouse actions
Yet to be written
@todo Yet to be written
*/

266
docs/doxygen/overviews/helloworld.h
View File

@@ -8,173 +8,173 @@
/**
@page overview_helloworld Hello World Example
@page overview_helloworld Hello World Example
Many people have requested a mini-sample to be published here
so that some quick judgment concerning syntax
and basic principles can be made, so here we go.
Many people have requested a mini-sample to be published here
so that some quick judgment concerning syntax
and basic principles can be made, so here we go.
First, you have to include wxWidgets' header files, of course. This can
be done on a file by file basis (such as <tt>@#include "wx/window.h"</tt>)
or using one global include (<tt>@#include "wx/wx.h"</tt>). This is
also useful on platforms which support precompiled headers such
as all major compilers on the Windows platform and GCC on Unix platforms.
First, you have to include wxWidgets' header files, of course. This can
be done on a file by file basis (such as <tt>@#include "wx/window.h"</tt>)
or using one global include (<tt>@#include "wx/wx.h"</tt>). This is
also useful on platforms which support precompiled headers such
as all major compilers on the Windows platform and GCC on Unix platforms.
@code
//
// file name: hworld.cpp
//
// purpose: wxWidgets "Hello world"
//
@code
//
// file name: hworld.cpp
//
// purpose: wxWidgets "Hello world"
//
// For compilers that support precompilation, includes "wx/wx.h".
#include "wx/wxprec.h"
// For compilers that support precompilation, includes "wx/wx.h".
#include "wx/wxprec.h"
#ifdef __BORLANDC__
#pragma hdrstop
#endif
#ifdef __BORLANDC__
#pragma hdrstop
#endif
#ifndef WX_PRECOMP
#include "wx/wx.h"
#endif
@endcode
#ifndef WX_PRECOMP
#include "wx/wx.h"
#endif
@endcode
Practically every app should define a new class derived from wxApp.
By overriding wxApp's OnInit() the program can be initialized,
e.g. by creating a new main window.
Practically every app should define a new class derived from wxApp.
By overriding wxApp's OnInit() the program can be initialized,
e.g. by creating a new main window.
@code
class MyApp: public wxApp
{
virtual bool OnInit();
};
@endcode
@code
class MyApp: public wxApp
{
virtual bool OnInit();
};
@endcode
The main window is created by deriving a class from wxFrame and
giving it a menu and a status bar in its constructor. Also, any class
that wishes to respond to any "event" (such as mouse clicks or
messages from the menu or a button) must declare an event table
using the macro below.
The main window is created by deriving a class from wxFrame and
giving it a menu and a status bar in its constructor. Also, any class
that wishes to respond to any "event" (such as mouse clicks or
messages from the menu or a button) must declare an event table
using the macro below.
Finally, the way to react to such events must be done in "handlers".
In our sample, we react to two menu items, one for "Quit" and one for
displaying an "About" window. These handlers should not be virtual.
Finally, the way to react to such events must be done in "handlers".
In our sample, we react to two menu items, one for "Quit" and one for
displaying an "About" window. These handlers should not be virtual.
@code
class MyFrame: public wxFrame
{
public:
MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
@code
class MyFrame: public wxFrame
{
public:
MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size);
void OnQuit(wxCommandEvent& event);
void OnAbout(wxCommandEvent& event);
void OnQuit(wxCommandEvent& event);
void OnAbout(wxCommandEvent& event);
private:
DECLARE_EVENT_TABLE()
};
@endcode
private:
DECLARE_EVENT_TABLE()
};
@endcode
In order to be able to react to a menu command, it must be given a unique
identifier such as a const or an enum.
In order to be able to react to a menu command, it must be given a unique
identifier such as a const or an enum.
@code
enum
{
ID_Quit = 1,
ID_About,
};
@endcode
@code
enum
{
ID_Quit = 1,
ID_About,
};
@endcode
We then proceed to actually implement an event table in which the events
are routed to their respective handler functions in the class MyFrame.
We then proceed to actually implement an event table in which the events
are routed to their respective handler functions in the class MyFrame.
There are predefined macros for routing all common events, ranging from
the selection of a list box entry to a resize event when a user resizes
a window on the screen. If -1 is given as the ID, the given handler will be
invoked for any event of the specified type, so that you could add just
one entry in the event table for all menu commands or all button commands etc.
There are predefined macros for routing all common events, ranging from
the selection of a list box entry to a resize event when a user resizes
a window on the screen. If -1 is given as the ID, the given handler will be
invoked for any event of the specified type, so that you could add just
one entry in the event table for all menu commands or all button commands etc.
The origin of the event can still be distinguished in the event handler as
the (only) parameter in an event handler is a reference to a wxEvent object,
which holds various information about the event (such as the ID of and a
pointer to the class, which emitted the event).
The origin of the event can still be distinguished in the event handler as
the (only) parameter in an event handler is a reference to a wxEvent object,
which holds various information about the event (such as the ID of and a
pointer to the class, which emitted the event).
@code
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(ID_Quit, MyFrame::OnQuit)
EVT_MENU(ID_About, MyFrame::OnAbout)
END_EVENT_TABLE()
@endcode
@code
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_MENU(ID_Quit, MyFrame::OnQuit)
EVT_MENU(ID_About, MyFrame::OnAbout)
END_EVENT_TABLE()
@endcode
As in all programs there must be a "main" function. Under wxWidgets main is implemented
using this macro, which creates an application instance and starts the program.
As in all programs there must be a "main" function. Under wxWidgets main is implemented
using this macro, which creates an application instance and starts the program.
@code
IMPLEMENT_APP(MyApp)
@endcode
@code
IMPLEMENT_APP(MyApp)
@endcode
As mentioned above, wxApp::OnInit() is called upon startup and should be
used to initialize the program, maybe showing a "splash screen" and creating
the main window (or several). The frame should get a title bar text ("Hello World")
and a position and start-up size. One frame can also be declared to be the
top window. Returning @true indicates a successful initialization.
As mentioned above, wxApp::OnInit() is called upon startup and should be
used to initialize the program, maybe showing a "splash screen" and creating
the main window (or several). The frame should get a title bar text ("Hello World")
and a position and start-up size. One frame can also be declared to be the
top window. Returning @true indicates a successful initialization.
@code
bool MyApp::OnInit()
{
MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
frame->Show( true );
SetTopWindow( frame );
return true;
}
@endcode
@code
bool MyApp::OnInit()
{
MyFrame *frame = new MyFrame( "Hello World", wxPoint(50,50), wxSize(450,340) );
frame->Show( true );
SetTopWindow( frame );
return true;
}
@endcode
In the constructor of the main window (or later on) we create a menu with two menu
items as well as a status bar to be shown at the bottom of the main window. Both have
to be "announced" to the frame with respective calls.
In the constructor of the main window (or later on) we create a menu with two menu
items as well as a status bar to be shown at the bottom of the main window. Both have
to be "announced" to the frame with respective calls.
@code
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
@code
MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size)
: wxFrame((wxFrame *)NULL, -1, title, pos, size)
{
wxMenu *menuFile = new wxMenu;
{
wxMenu *menuFile = new wxMenu;
menuFile->Append( ID_About, "" );
menuFile->AppendSeparator();
menuFile->Append( ID_Quit, "E" );
menuFile->Append( ID_About, "" );
menuFile->AppendSeparator();
menuFile->Append( ID_Quit, "E" );
wxMenuBar *menuBar = new wxMenuBar;
menuBar->Append( menuFile, "" );
wxMenuBar *menuBar = new wxMenuBar;
menuBar->Append( menuFile, "" );
SetMenuBar( menuBar );
SetMenuBar( menuBar );
CreateStatusBar();
SetStatusText( "Welcome to wxWidgets!" );
}
@endcode
CreateStatusBar();
SetStatusText( "Welcome to wxWidgets!" );
}
@endcode
Here are the actual event handlers. MyFrame::OnQuit() closes the main window
by calling Close(). The parameter @true indicates that other windows have no veto
power such as after asking "Do you really want to close?". If there is no other
main window left, the application will quit.
Here are the actual event handlers. MyFrame::OnQuit() closes the main window
by calling Close(). The parameter @true indicates that other windows have no veto
power such as after asking "Do you really want to close?". If there is no other
main window left, the application will quit.
@code
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
Close( true );
}
@endcode
@code
void MyFrame::OnQuit(wxCommandEvent& WXUNUSED(event))
{
Close( true );
}
@endcode
MyFrame::OnAbout() will display a small window with some text in it. In this
case a typical "About" window with information about the program.
MyFrame::OnAbout() will display a small window with some text in it. In this
case a typical "About" window with information about the program.
@code
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
wxMessageBox( "This is a wxWidgets' Hello world sample",
"About Hello World", wxOK | wxICON_INFORMATION );
}
@endcode
@code
void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
{
wxMessageBox( "This is a wxWidgets' Hello world sample",
"About Hello World", wxOK | wxICON_INFORMATION );
}
@endcode
*/

832
docs/doxygen/overviews/html.h
View File

@@ -8,579 +8,579 @@
/**
@page overview_html wxHTML Overview
@page overview_html wxHTML Overview
The wxHTML library provides classes for parsing and displaying HTML.
It is not intended to be a high-end HTML browser. If you are looking for
something like that try <http://www.mozilla.org/>.
The wxHTML library provides classes for parsing and displaying HTML.
It is not intended to be a high-end HTML browser. If you are looking for
something like that try <http://www.mozilla.org/>.
wxHTML can be used as a generic rich text viewer - for example to display
a nice About Box (like those of GNOME apps) or to display the result of
database searching. There is a wxFileSystem class which allows you to use
your own virtual file systems.
wxHTML can be used as a generic rich text viewer - for example to display
a nice About Box (like those of GNOME apps) or to display the result of
database searching. There is a wxFileSystem class which allows you to use
your own virtual file systems.
wxHtmlWindow supports tag handlers. This means that you can easily
extend wxHtml library with new, unsupported tags. Not only that,
you can even use your own application-specific tags!
wxHtmlWindow supports tag handlers. This means that you can easily
extend wxHtml library with new, unsupported tags. Not only that,
you can even use your own application-specific tags!
See @c src/html/m_*.cpp files for details.
See @c src/html/m_*.cpp files for details.
There is a generic wxHtmlParser class, independent of wxHtmlWindow.
There is a generic wxHtmlParser class, independent of wxHtmlWindow.
@li @ref overview_html_quickstart
@li @ref overview_html_printing
@li @ref overview_html_helpformats
@li @ref overview_html_filters
@li @ref overview_html_cells
@li @ref overview_html_handlers
@li @ref overview_html_supptags
@li @ref overview_html_quickstart
@li @ref overview_html_printing
@li @ref overview_html_helpformats
@li @ref overview_html_filters
@li @ref overview_html_cells
@li @ref overview_html_handlers
@li @ref overview_html_supptags
<hr>
<hr>
@section overview_html_quickstart wxHTML quick start
@section overview_html_quickstart wxHTML quick start
@subsection overview_html_quickstart_disphtml Displaying HTML
@subsection overview_html_quickstart_disphtml Displaying HTML
First of all, you must include @c wx/wxhtml.h.
First of all, you must include @c wx/wxhtml.h.
Class wxHtmlWindow (derived from wxScrolledWindow) is used to display HTML documents.
Class wxHtmlWindow (derived from wxScrolledWindow) is used to display HTML documents.
It has two important methods: wxHtmlWindow::LoadPage and wxHtmlWindow::SetPage.
LoadPage loads and displays HTML file while SetPage displays directly the
passed @b string. See the example:
It has two important methods: wxHtmlWindow::LoadPage and wxHtmlWindow::SetPage.
LoadPage loads and displays HTML file while SetPage displays directly the
passed @b string. See the example:
@code
mywin -> LoadPage("test.htm");
mywin -> SetPage("htmlbody"
"h1Error/h1"
"Some error occurred :-H)"
"/body/hmtl");
@endcode
@code
mywin -> LoadPage("test.htm");
mywin -> SetPage("htmlbody"
"h1Error/h1"
"Some error occurred :-H)"
"/body/hmtl");
@endcode
@subsection overview_html_quickstart_disphelp Displaying Help
@subsection overview_html_quickstart_disphelp Displaying Help
See wxHtmlHelpController.
See wxHtmlHelpController.
@subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
@subsection overview_html_quickstart_settingup Setting up wxHtmlWindow
Because wxHtmlWindow is derived from wxScrolledWindow and not from
wxFrame, it doesn't have visible frame. But the user usually wants to see
the title of HTML page displayed somewhere and the frame's titlebar is
the ideal place for it.
Because wxHtmlWindow is derived from wxScrolledWindow and not from
wxFrame, it doesn't have visible frame. But the user usually wants to see
the title of HTML page displayed somewhere and the frame's titlebar is
the ideal place for it.
wxHtmlWindow provides 2 methods in order to handle this:
wxHtmlWindow::SetRelatedFrame and wxHtmlWindow::SetRelatedStatusBar.
See the example:
wxHtmlWindow provides 2 methods in order to handle this:
wxHtmlWindow::SetRelatedFrame and wxHtmlWindow::SetRelatedStatusBar.
See the example:
@code
html = new wxHtmlWindow(this);
html -> SetRelatedFrame(this, "HTML : %%s");
html -> SetRelatedStatusBar(0);
@endcode
@code
html = new wxHtmlWindow(this);
html -> SetRelatedFrame(this, "HTML : %%s");
html -> SetRelatedStatusBar(0);
@endcode
The first command associates the HTML object with its parent frame
(this points to wxFrame object there) and sets the format of the title.
Page title "Hello, world!" will be displayed as "HTML : Hello, world!"
in this example.
The first command associates the HTML object with its parent frame
(this points to wxFrame object there) and sets the format of the title.
Page title "Hello, world!" will be displayed as "HTML : Hello, world!"
in this example.
The second command sets which frame's status bar should be used to display
browser's messages (such as "Loading..." or "Done" or hypertext links).
The second command sets which frame's status bar should be used to display
browser's messages (such as "Loading..." or "Done" or hypertext links).
@subsection overview_html_quickstart_custom Customizing wxHtmlWindow
@subsection overview_html_quickstart_custom Customizing wxHtmlWindow
You can customize wxHtmlWindow by setting font size, font face and
borders (space between border of window and displayed HTML). Related functions:
You can customize wxHtmlWindow by setting font size, font face and
borders (space between border of window and displayed HTML). Related functions:
@li wxHtmlWindow::SetFonts
@li wxHtmlWindow::SetBorders
@li wxHtmlWindow::ReadCustomization
@li wxHtmlWindow::WriteCustomization
@li wxHtmlWindow::SetFonts
@li wxHtmlWindow::SetBorders
@li wxHtmlWindow::ReadCustomization
@li wxHtmlWindow::WriteCustomization
The last two functions are used to store user customization info wxConfig stuff
(for example in the registry under Windows, or in a dotfile under Unix).
The last two functions are used to store user customization info wxConfig stuff
(for example in the registry under Windows, or in a dotfile under Unix).
@section overview_html_printing HTML Printing
@section overview_html_printing HTML Printing
The wxHTML library provides printing facilities with several levels of complexity.
The easiest way to print an HTML document is to use the wxHtmlEasyPrinting class.
The wxHTML library provides printing facilities with several levels of complexity.
The easiest way to print an HTML document is to use the wxHtmlEasyPrinting class.
It lets you print HTML documents with only one command and you don't have to worry
about deriving from the wxPrintout class at all. It is only a simple wrapper around the
wxHtmlPrintout, normal wxWidgets printout class.
It lets you print HTML documents with only one command and you don't have to worry
about deriving from the wxPrintout class at all. It is only a simple wrapper around the
wxHtmlPrintout, normal wxWidgets printout class.
And finally there is the low level class wxHtmlDCRenderer which you can use to
render HTML into a rectangular area on any DC.
And finally there is the low level class wxHtmlDCRenderer which you can use to
render HTML into a rectangular area on any DC.
It supports rendering into multiple rectangles with the same
width. (The most common use of this is placing one rectangle on each page or
printing into two columns.)
It supports rendering into multiple rectangles with the same
width. (The most common use of this is placing one rectangle on each page or
printing into two columns.)
@section overview_html_helpformats Help Files Format
@section overview_html_helpformats Help Files Format
wxHTML library uses a reduced version of MS HTML Workshop format.
Tex2RTF can produce these files when generating HTML, if you set
@b htmlWorkshopFiles to @true in your tex2rtf.ini file.
(See wxHtmlHelpController for help controller description.)
wxHTML library uses a reduced version of MS HTML Workshop format.
Tex2RTF can produce these files when generating HTML, if you set
@b htmlWorkshopFiles to @true in your tex2rtf.ini file.
(See wxHtmlHelpController for help controller description.)
A @b book consists of three files: the header file, the contents file
and the index file.
A @b book consists of three files: the header file, the contents file
and the index file.
You can make a regular zip archive of these files, plus the HTML and any
image files, for wxHTML (or helpview) to read; and the @c .zip file can
optionally be renamed to @c .htb.
You can make a regular zip archive of these files, plus the HTML and any
image files, for wxHTML (or helpview) to read; and the @c .zip file can
optionally be renamed to @c .htb.
@subsection overview_html_helpformats_hhp Header file (.hhp)
@subsection overview_html_helpformats_hhp Header file (.hhp)
The header file must contain these lines (and may contain additional lines
which are ignored):
The header file must contain these lines (and may contain additional lines
which are ignored):
@code
Contents file=filename.hhc
Index file=filename.hhk
Title=title of your book
Default topic=default page to be displayed.htm
@endcode
@code
Contents file=filename.hhc
Index file=filename.hhk
Title=title of your book
Default topic=default page to be displayed.htm
@endcode
All filenames (including the Default topic) are relative to the
location of the @c .hhp file.
All filenames (including the Default topic) are relative to the
location of the @c .hhp file.
@note For localization, in addition the @c .hhp file may contain the line
@code
@note For localization, in addition the @c .hhp file may contain the line
@code
Charset=rfc_charset
@endcode
which specifies what charset (e.g. "iso8859_1") was used in contents
and index files. Please note that this line is incompatible with
MS HTML Help Workshop and it would either silently remove it or complain
with some error. See also @ref overview_nonenglish.
@endcode
which specifies what charset (e.g. "iso8859_1") was used in contents
and index files. Please note that this line is incompatible with
MS HTML Help Workshop and it would either silently remove it or complain
with some error. See also @ref overview_nonenglish.
@subsection overview_html_helpformats_hhc Contents file (.hhc)
@subsection overview_html_helpformats_hhc Contents file (.hhc)
Contents file has HTML syntax and it can be parsed by regular HTML parser.
It contains exactly one list (@c &lt;ul&gt;....@c &lt;/ul&gt; statement):
Contents file has HTML syntax and it can be parsed by regular HTML parser.
It contains exactly one list (@c &lt;ul&gt;....@c &lt;/ul&gt; statement):
@code
<ul>
@code
<ul>
<li><object type="text/sitemap">
<li><object type="text/sitemap">
<param name="Name" value="@topic name@">
<param name="ID" value=@numeric_id@>
<param name="Local" value="@filename.htm@">
</object>
<li><object type="text/sitemap">
<li><object type="text/sitemap">
<param name="Name" value="@topic name@">
<param name="ID" value=@numeric_id@>
<param name="Local" value="@filename.htm@">
</object>
...
</ul>
@endcode
...
</ul>
@endcode
You can modify value attributes of param tags.
The <em>topic name</em> is name of chapter/topic as is displayed in
contents, <em>filename.htm</em> is the HTML page name (relative to the @c .hhp file)
and <em>numeric_id</em> is optional - it is used only when you use wxHtmlHelpController::Display(int).
You can modify value attributes of param tags.
The <em>topic name</em> is name of chapter/topic as is displayed in
contents, <em>filename.htm</em> is the HTML page name (relative to the @c .hhp file)
and <em>numeric_id</em> is optional - it is used only when you use wxHtmlHelpController::Display(int).
Items in the list may be nested - one @c &lt;li&gt; statement may contain a @c &lt;ul&gt; sub-statement:
Items in the list may be nested - one @c &lt;li&gt; statement may contain a @c &lt;ul&gt; sub-statement:
@code
<ul>
@code
<ul>
<li><object type="text/sitemap">
<param name="Name" value="Top node">
<param name="Local" value="top.htm">
</object>
<ul>
<li><object type="text/sitemap">
<param name="Name" value="subnode in topnode">
<param name="Local" value="subnode1.htm">
</object>
...
</ul>
<li><object type="text/sitemap">
<param name="Name" value="Top node">
<param name="Local" value="top.htm">
</object>
<ul>
<li><object type="text/sitemap">
<param name="Name" value="subnode in topnode">
<param name="Local" value="subnode1.htm">
</object>
...
</ul>
<li><object type="text/sitemap">
<param name="Name" value="Another Top">
<param name="Local" value="top2.htm">
</object>
...
<li><object type="text/sitemap">
<param name="Name" value="Another Top">
<param name="Local" value="top2.htm">
</object>
...
</ul>
@endcode
</ul>
@endcode
@subsection overview_html_helpformats_hhk Index file (.hhk)
@subsection overview_html_helpformats_hhk Index file (.hhk)
Index files have same format as contents file except that ID params are ignored
and sublists are @b not allowed.
Index files have same format as contents file except that ID params are ignored
and sublists are @b not allowed.
@section overview_html_filters Input Filters
@section overview_html_filters Input Filters
The wxHTML library provides a mechanism for reading and displaying
files of many different file formats.
The wxHTML library provides a mechanism for reading and displaying
files of many different file formats.
wxHtmlWindow::LoadPage can load not only HTML files but any known file.
To make a file type known to wxHtmlWindow you must create a wxHtmlFilter filter and
register it using wxHtmlWindow::AddFilter.
wxHtmlWindow::LoadPage can load not only HTML files but any known file.
To make a file type known to wxHtmlWindow you must create a wxHtmlFilter filter and
register it using wxHtmlWindow::AddFilter.
@section overview_html_cells Cells and Containers
@section overview_html_cells Cells and Containers
This article describes mechanism used by wxHtmlWinParser and
wxHtmlWindow to parse and display HTML documents.
This article describes mechanism used by wxHtmlWinParser and
wxHtmlWindow to parse and display HTML documents.
@subsection overview_html_cells_cells Cells
@subsection overview_html_cells_cells Cells
You can divide any text (or HTML) into small fragments. Let's call these
fragments @b cells. Cell is for example one word, horizontal line, image
or any other part of document. Each cell has width and height (except special
"magic" cells with zero dimensions - e.g. colour changers or font changers).
See wxHtmlCell.
You can divide any text (or HTML) into small fragments. Let's call these
fragments @b cells. Cell is for example one word, horizontal line, image
or any other part of document. Each cell has width and height (except special
"magic" cells with zero dimensions - e.g. colour changers or font changers).
See wxHtmlCell.
@subsection overview_html_cells_containers Containers
@subsection overview_html_cells_containers Containers
Container is kind of cell that may contain sub-cells. Its size depends
on number and sizes of its sub-cells (and also depends on width of window).
See wxHtmlContainerCell, wxHtmlCell::Layout. This image shows the cells and
containers:
Container is kind of cell that may contain sub-cells. Its size depends
on number and sizes of its sub-cells (and also depends on width of window).
See wxHtmlContainerCell, wxHtmlCell::Layout. This image shows the cells and
containers:
@image html overview_html_contbox.png
@image html overview_html_contbox.png
@subsection overview_html_cells_conttaghandler Using Containers in Tag Handler
@subsection overview_html_cells_conttaghandler Using Containers in Tag Handler
wxHtmlWinParser provides a user-friendly way of managing containers.
It is based on the idea of opening and closing containers.
wxHtmlWinParser provides a user-friendly way of managing containers.
It is based on the idea of opening and closing containers.
Use wxHtmlWinParser::OpenContainer to open new a container @e within an already
opened container.
This new container is a @e sub-container of the old one. (If you want to create a
new container with the same depth level you can call @c CloseContainer(); OpenContainer();.)
Use wxHtmlWinParser::OpenContainer to open new a container @e within an already
opened container.
This new container is a @e sub-container of the old one. (If you want to create a
new container with the same depth level you can call @c CloseContainer(); OpenContainer();.)
Use wxHtmlWinParser::CloseContainer to close the container.
This doesn't create a new container with same depth level but it returns "control"
to the parent container. See explanation:
Use wxHtmlWinParser::CloseContainer to close the container.
This doesn't create a new container with same depth level but it returns "control"
to the parent container. See explanation:
@image html overview_html_cont.png
@image html overview_html_cont.png
There clearly must be same number of calls to OpenContainer as to
CloseContainer.
There clearly must be same number of calls to OpenContainer as to
CloseContainer.
@subsubsection overview_html_cells_conttaghandler_example Example
@subsubsection overview_html_cells_conttaghandler_example Example
This code creates a new paragraph (container at same depth level)
with "Hello, world!":
This code creates a new paragraph (container at same depth level)
with "Hello, world!":
@code
m_WParser -> CloseContainer();
c = m_WParser -> OpenContainer();
@code
m_WParser -> CloseContainer();
c = m_WParser -> OpenContainer();
m_WParser -> AddText("Hello, ");
m_WParser -> AddText("world!");
m_WParser -> AddText("Hello, ");
m_WParser -> AddText("world!");
m_WParser -> CloseContainer();
m_WParser -> OpenContainer();
@endcode
m_WParser -> CloseContainer();
m_WParser -> OpenContainer();
@endcode
and here is image of the situation:
and here is image of the situation:
@image html overview_html_hello.png
@image html overview_html_hello.png
You can see that there was an opened container before the code was executed.
We closed it, created our own container, then closed our container and opened
new container.
You can see that there was an opened container before the code was executed.
We closed it, created our own container, then closed our container and opened
new container.
The result was that we had @e same depth level after executing.
This is general rule that should be followed by tag handlers:
leave depth level of containers unmodified (in other words, number of
OpenContainer and CloseContainer calls should be same within
wxHtmlTagHandler::HandleTag's body).
The result was that we had @e same depth level after executing.
This is general rule that should be followed by tag handlers:
leave depth level of containers unmodified (in other words, number of
OpenContainer and CloseContainer calls should be same within
wxHtmlTagHandler::HandleTag's body).
Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead
of adding text to the parser directly.
Notice that it would be usually better to use wxHtmlContainerCell::InsertCell instead
of adding text to the parser directly.
@section overview_html_handlers Tag Handlers
@section overview_html_handlers Tag Handlers
The wxHTML library provides architecture of pluggable @e tag handlers.
Tag handler is class that understands particular HTML tag (or tags) and is
able to interpret it.
The wxHTML library provides architecture of pluggable @e tag handlers.
Tag handler is class that understands particular HTML tag (or tags) and is
able to interpret it.
wxHtmlWinParser has a static table of @b modules.
Each module contains one or more tag handlers. Each time a new wxHtmlWinParser
object is constructed all modules are scanned and handlers are added
to wxHtmlParser's list of available handlers (note: wxHtmlParser's list
is non-static).
wxHtmlWinParser has a static table of @b modules.
Each module contains one or more tag handlers. Each time a new wxHtmlWinParser
object is constructed all modules are scanned and handlers are added
to wxHtmlParser's list of available handlers (note: wxHtmlParser's list
is non-static).
@subsection overview_html_handlers_howworks How it works
@subsection overview_html_handlers_howworks How it works
Common tag handler's wxHtmlTagHandler::HandleTag method works in four steps:
Common tag handler's wxHtmlTagHandler::HandleTag method works in four steps:
@li Save state of parent parser into local variables
@li Change parser state according to tag's params
@li Parse text between the tag and paired ending tag (if present)
@li Restore original parser state
@li Save state of parent parser into local variables
@li Change parser state according to tag's params
@li Parse text between the tag and paired ending tag (if present)
@li Restore original parser state
See wxHtmlWinParser for methods for modifying parser's state.
In general you can do things like opening/closing containers, changing colors, fonts etc.
See wxHtmlWinParser for methods for modifying parser's state.
In general you can do things like opening/closing containers, changing colors, fonts etc.
@subsection overview_html_handlers_custom Providing own tag handlers
@subsection overview_html_handlers_custom Providing own tag handlers
You should create a new .cpp file and place the following lines into it:
You should create a new .cpp file and place the following lines into it:
@code
#include <mod_templ.h>
#include <forcelink.h>
FORCE_LINK_ME(yourmodulefilenamewithoutcpp)
@endcode
@code
#include <mod_templ.h>
#include <forcelink.h>
FORCE_LINK_ME(yourmodulefilenamewithoutcpp)
@endcode
Then you must define handlers and one module.
Then you must define handlers and one module.
@subsection overview_html_handlers_tag Tag handlers
@subsection overview_html_handlers_tag Tag handlers
The handler is derived from wxHtmlWinTagHandler (or directly from wxHtmlTagHandler).
The handler is derived from wxHtmlWinTagHandler (or directly from wxHtmlTagHandler).
You can use set of macros to define the handler (see src/html/m_*.cpp files
for details). Handler definition must start with @b TAG_HANDLER_BEGIN macro
and end with @b TAG_HANDLER_END macro.
You can use set of macros to define the handler (see src/html/m_*.cpp files
for details). Handler definition must start with @b TAG_HANDLER_BEGIN macro
and end with @b TAG_HANDLER_END macro.
I strongly recommend to have a look at @e include/wxhtml/mod_templ.h file.
Otherwise you won't understand the structure of macros.
I strongly recommend to have a look at @e include/wxhtml/mod_templ.h file.
Otherwise you won't understand the structure of macros.
See macros reference:
@li @b TAG_HANDLER_BEGIN(@e name, @e tags):
Starts handler definition. @e name is handler identifier (in fact
part of class name), @e tags is string containing list of tags
supported by this handler (in uppercase). This macro derives new class from
wxHtmlWinTagHandler and implements it is wxHtmlTagHandler::GetSupportedTags method.
Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")
See macros reference:
@li @b TAG_HANDLER_BEGIN(@e name, @e tags):
Starts handler definition. @e name is handler identifier (in fact
part of class name), @e tags is string containing list of tags
supported by this handler (in uppercase). This macro derives new class from
wxHtmlWinTagHandler and implements it is wxHtmlTagHandler::GetSupportedTags method.
Example: TAG_HANDLER_BEGIN(FONTS, "B,I,U,T")
@li @b TAG_HANDLER_VARS:
This macro starts block of variables definitions. (Variables are identical
to class attributes.) Example:
@li @b TAG_HANDLER_VARS:
This macro starts block of variables definitions. (Variables are identical
to class attributes.) Example:
@code
TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
@code
TAG_HANDLER_BEGIN(VARS_ONLY, "CRAZYTAG")
TAG_HANDLER_VARS
int my_int_var;
wxString something_else;
TAG_HANDLER_END(VARS_ONLY)
@endcode
TAG_HANDLER_END(VARS_ONLY)
@endcode
This macro is used only in rare cases.
This macro is used only in rare cases.
@li @b TAG_HANDLER_CONSTR(@e name):
This macro supplies object constructor. @e name is same name as the one
from TAG_HANDLER_BEGIN macro. Body of constructor follow after
this macro (you must use { and } ). Example:
@li @b TAG_HANDLER_CONSTR(@e name):
This macro supplies object constructor. @e name is same name as the one
from TAG_HANDLER_BEGIN macro. Body of constructor follow after
this macro (you must use { and } ). Example:
@code
TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
@code
TAG_HANDLER_BEGIN(VARS2, "CRAZYTAG")
TAG_HANDLER_VARS
int my_int_var;
TAG_HANDLER_CONSTR(vars2)
{ // !!!!!!
my_int_var = 666;
my_int_var = 666;
} // !!!!!!
TAG_HANDLER_END(VARS2)
@endcode
TAG_HANDLER_END(VARS2)
@endcode
Never used in wxHTML :-)
Never used in wxHTML :-)
@li @b TAG_HANDLER_PROC(@e varib):
This is very important macro. It defines wxHtmlTagHandler::HandleTag
method. @e varib is name of parameter passed to the method, usually
@e tag. Body of method follows after this macro.
Note than you must use { and } !
Example:
@li @b TAG_HANDLER_PROC(@e varib):
This is very important macro. It defines wxHtmlTagHandler::HandleTag
method. @e varib is name of parameter passed to the method, usually
@e tag. Body of method follows after this macro.
Note than you must use { and } !
Example:
@code
TAG_HANDLER_BEGIN(TITLE, "TITLE")
@code
TAG_HANDLER_BEGIN(TITLE, "TITLE")
TAG_HANDLER_PROC(tag)
{
printf("TITLE found...\n");
printf("TITLE found...\n");
}
TAG_HANDLER_END(TITLE)
@endcode
TAG_HANDLER_END(TITLE)
@endcode
@li @b TAG_HANDLER_END(@e name):
Ends definition of tag handler @e name.
@li @b TAG_HANDLER_END(@e name):
Ends definition of tag handler @e name.
@subsection overview_html_handlers_modules Tags Modules
@subsection overview_html_handlers_modules Tags Modules
You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and
TAGS_MODULE_END to inherit new module from
wxHtmlTagsModule and to create instance of it.
You can use set of 3 macros TAGS_MODULE_BEGIN, TAGS_MODULE_ADD and
TAGS_MODULE_END to inherit new module from
wxHtmlTagsModule and to create instance of it.
See macros reference:
See macros reference:
@li @b TAGS_MODULE_BEGIN(@e modname):
Begins module definition. @e modname is part of class name and must be unique.
@li @b TAGS_MODULE_ADD(@e name):
Adds the handler to this module. @e name is the identifier from TAG_HANDLER_BEGIN.
@li @b TAGS_MODULE_END(@e modname):
Ends the definition of module.
Example:
@li @b TAGS_MODULE_BEGIN(@e modname):
Begins module definition. @e modname is part of class name and must be unique.
@li @b TAGS_MODULE_ADD(@e name):
Adds the handler to this module. @e name is the identifier from TAG_HANDLER_BEGIN.
@li @b TAGS_MODULE_END(@e modname):
Ends the definition of module.
Example:
@code
TAGS_MODULE_BEGIN(Examples)
@code
TAGS_MODULE_BEGIN(Examples)
TAGS_MODULE_ADD(VARS_ONLY)
TAGS_MODULE_ADD(VARS2)
TAGS_MODULE_ADD(TITLE)
TAGS_MODULE_END(Examples)
@endcode
TAGS_MODULE_END(Examples)
@endcode
@section overview_html_supptags Tags supported by wxHTML
@section overview_html_supptags Tags supported by wxHTML
wxHTML is not full implementation of HTML standard. Instead, it supports most
common tags so that it is possible to display @e simple HTML documents with it.
(For example it works fine with pages created in Netscape Composer or generated by tex2rtf).
wxHTML is not full implementation of HTML standard. Instead, it supports most
common tags so that it is possible to display @e simple HTML documents with it.
(For example it works fine with pages created in Netscape Composer or generated by tex2rtf).
Following tables list all tags known to wxHTML, together with supported parameters.
Following tables list all tags known to wxHTML, together with supported parameters.
A tag has general form of @c tagname param_1 param_2 ... param_n where param_i is
either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent.
Unless stated otherwise, wxHTML is case-insensitive.
A tag has general form of @c tagname param_1 param_2 ... param_n where param_i is
either @c paramname="paramvalue" or @c paramname=paramvalue - these two are equivalent.
Unless stated otherwise, wxHTML is case-insensitive.
@subsection overview_html_supptags_commonvalues Table of common parameter values
@subsection overview_html_supptags_commonvalues Table of common parameter values
We will use these substitutions in tags descriptions:
We will use these substitutions in tags descriptions:
@code
[alignment] CENTER
LEFT
RIGHT
JUSTIFY
@code
[alignment] CENTER
LEFT
RIGHT
JUSTIFY
[v_alignment] TOP
BOTTOM
CENTER
[v_alignment] TOP
BOTTOM
CENTER
[color] HTML 4.0-compliant colour specification
[color] HTML 4.0-compliant colour specification
[fontsize] -2
-1
+0
+1
+2
+3
+4
1
2
3
4
5
6
7
[fontsize] -2
-1
+0
+1
+2
+3
+4
1
2
3
4
5
6
7
[pixels] integer value that represents dimension in pixels
[pixels] integer value that represents dimension in pixels
[percent] i%
where i is integer
[percent] i%
where i is integer
[url] an URL
[url] an URL
[string] text string
[string] text string
[coords] c(1),c(2),c(3),...,c(n)
where c(i) is integer
@endcode
[coords] c(1),c(2),c(3),...,c(n)
where c(i) is integer
@endcode
@subsection overview_html_supptags_list List of supported tags
@subsection overview_html_supptags_list List of supported tags
@code
A NAME=[string]
HREF=[url]
TARGET=[target window spec]
ADDRESS
AREA SHAPE=POLY
SHAPE=CIRCLE
SHAPE=RECT
COORDS=[coords]
HREF=[url]
B
BIG
BLOCKQUOTE
BODY TEXT=[color]
LINK=[color]
BGCOLOR=[color]
BR ALIGN=[alignment]
CENTER
CITE
CODE
DD
DIV ALIGN=[alignment]
DL
DT
EM
FONT COLOR=[color]
SIZE=[fontsize]
FACE=[comma-separated list of facenames]
HR ALIGN=[alignment]
SIZE=[pixels]
WIDTH=[percent|pixels]
NOSHADE
H1
H2
H3
H4
H5
H6
I
IMG SRC=[url]
WIDTH=[pixels]
HEIGHT=[pixels]
ALIGN=TEXTTOP
ALIGN=CENTER
ALIGN=ABSCENTER
ALIGN=BOTTOM
USEMAP=[url]
KBD
LI
MAP NAME=[string]
META HTTP-EQUIV="Content-Type"
CONTENT=[string]
OL
P ALIGN=[alignment]
PRE
SAMP
SMALL
STRIKE
STRONG
SUB
SUP
TABLE ALIGN=[alignment]
WIDTH=[percent|pixels]
BORDER=[pixels]
VALIGN=[v_alignment]
BGCOLOR=[color]
CELLSPACING=[pixels]
CELLPADDING=[pixels]
TD ALIGN=[alignment]
VALIGN=[v_alignment]
BGCOLOR=[color]
WIDTH=[percent|pixels]
COLSPAN=[pixels]
ROWSPAN=[pixels]
NOWRAP
TH ALIGN=[alignment]
VALIGN=[v_alignment]
BGCOLOR=[color]
WIDTH=[percent|pixels]
COLSPAN=[pixels]
ROWSPAN=[pixels]
TITLE
TR ALIGN=[alignment]
VALIGN=[v_alignment]
BGCOLOR=[color]
TT
U
UL
@endcode
@code
A NAME=[string]
HREF=[url]
TARGET=[target window spec]
ADDRESS
AREA SHAPE=POLY
SHAPE=CIRCLE
SHAPE=RECT
COORDS=[coords]
HREF=[url]
B
BIG
BLOCKQUOTE
BODY TEXT=[color]
LINK=[color]
BGCOLOR=[color]
BR ALIGN=[alignment]
CENTER
CITE
CODE
DD
DIV ALIGN=[alignment]
DL
DT
EM
FONT COLOR=[color]
SIZE=[fontsize]
FACE=[comma-separated list of facenames]
HR ALIGN=[alignment]
SIZE=[pixels]
WIDTH=[percent|pixels]
NOSHADE
H1
H2
H3
H4
H5
H6
I
IMG SRC=[url]
WIDTH=[pixels]
HEIGHT=[pixels]
ALIGN=TEXTTOP
ALIGN=CENTER
ALIGN=ABSCENTER
ALIGN=BOTTOM
USEMAP=[url]
KBD
LI
MAP NAME=[string]
META HTTP-EQUIV="Content-Type"
CONTENT=[string]
OL
P ALIGN=[alignment]
PRE
SAMP
SMALL
STRIKE
STRONG
SUB
SUP
TABLE ALIGN=[alignment]
WIDTH=[percent|pixels]
BORDER=[pixels]
VALIGN=[v_alignment]
BGCOLOR=[color]
CELLSPACING=[pixels]
CELLPADDING=[pixels]
TD ALIGN=[alignment]
VALIGN=[v_alignment]
BGCOLOR=[color]
WIDTH=[percent|pixels]
COLSPAN=[pixels]
ROWSPAN=[pixels]
NOWRAP
TH ALIGN=[alignment]
VALIGN=[v_alignment]
BGCOLOR=[color]
WIDTH=[percent|pixels]
COLSPAN=[pixels]
ROWSPAN=[pixels]
TITLE
TR ALIGN=[alignment]
VALIGN=[v_alignment]
BGCOLOR=[color]
TT
U
UL
@endcode
*/

2
docs/doxygen/overviews/listctrl.h
View File

@@ -12,7 +12,7 @@
Classes: wxListCtrl, wxImageList
Sorry, this topic hasn't been written yet.
@todo Sorry, this topic hasn't been written yet.
*/