// Constants
// TypeFlag values
-enum {
+enum wxTarType
+{
wxTAR_REGTYPE = '0', // regular file
wxTAR_LNKTYPE = '1', // hard link
wxTAR_SYMTYPE = '2', // symbolic link
};
// Flags to indicate which attributes are being applied
-
-#define wxTEXT_ATTR_TEXT_COLOUR 0x00000001
-#define wxTEXT_ATTR_BACKGROUND_COLOUR 0x00000002
-#define wxTEXT_ATTR_FONT_FACE 0x00000004
-#define wxTEXT_ATTR_FONT_SIZE 0x00000008
-#define wxTEXT_ATTR_FONT_WEIGHT 0x00000010
-#define wxTEXT_ATTR_FONT_ITALIC 0x00000020
-#define wxTEXT_ATTR_FONT_UNDERLINE 0x00000040
-#define wxTEXT_ATTR_FONT_ENCODING 0x02000000
-#define wxTEXT_ATTR_FONT \
- ( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \
- wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING )
-#define wxTEXT_ATTR_ALIGNMENT 0x00000080
-#define wxTEXT_ATTR_LEFT_INDENT 0x00000100
-#define wxTEXT_ATTR_RIGHT_INDENT 0x00000200
-#define wxTEXT_ATTR_TABS 0x00000400
-
-#define wxTEXT_ATTR_PARA_SPACING_AFTER 0x00000800
-#define wxTEXT_ATTR_PARA_SPACING_BEFORE 0x00001000
-#define wxTEXT_ATTR_LINE_SPACING 0x00002000
-#define wxTEXT_ATTR_CHARACTER_STYLE_NAME 0x00004000
-#define wxTEXT_ATTR_PARAGRAPH_STYLE_NAME 0x00008000
-#define wxTEXT_ATTR_LIST_STYLE_NAME 0x00010000
-#define wxTEXT_ATTR_BULLET_STYLE 0x00020000
-#define wxTEXT_ATTR_BULLET_NUMBER 0x00040000
-#define wxTEXT_ATTR_BULLET_TEXT 0x00080000
-#define wxTEXT_ATTR_BULLET_NAME 0x00100000
-#define wxTEXT_ATTR_URL 0x00200000
-#define wxTEXT_ATTR_PAGE_BREAK 0x00400000
-#define wxTEXT_ATTR_EFFECTS 0x00800000
-#define wxTEXT_ATTR_OUTLINE_LEVEL 0x01000000
-
-/*!
- * Character and paragraph combined styles
- */
-
-#define wxTEXT_ATTR_CHARACTER (wxTEXT_ATTR_FONT|wxTEXT_ATTR_FONT_ENCODING|wxTEXT_ATTR_EFFECTS|wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL)
-
-#define wxTEXT_ATTR_PARAGRAPH (wxTEXT_ATTR_ALIGNMENT|wxTEXT_ATTR_LEFT_INDENT|wxTEXT_ATTR_RIGHT_INDENT|wxTEXT_ATTR_TABS|\
- wxTEXT_ATTR_PARA_SPACING_BEFORE|wxTEXT_ATTR_PARA_SPACING_AFTER|wxTEXT_ATTR_LINE_SPACING|\
- wxTEXT_ATTR_BULLET_STYLE|wxTEXT_ATTR_BULLET_NUMBER|wxTEXT_ATTR_BULLET_TEXT|wxTEXT_ATTR_BULLET_NAME|\
- wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL)
-
-#define wxTEXT_ATTR_ALL (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH)
+enum wxTextAttrFlags
+{
+ wxTEXT_ATTR_TEXT_COLOUR = 0x00000001,
+ wxTEXT_ATTR_BACKGROUND_COLOUR = 0x00000002,
+ wxTEXT_ATTR_FONT_FACE = 0x00000004,
+ wxTEXT_ATTR_FONT_SIZE = 0x00000008,
+ wxTEXT_ATTR_FONT_WEIGHT = 0x00000010,
+ wxTEXT_ATTR_FONT_ITALIC = 0x00000020,
+ wxTEXT_ATTR_FONT_UNDERLINE = 0x00000040,
+ wxTEXT_ATTR_FONT_ENCODING = 0x02000000,
+ wxTEXT_ATTR_FONT = \
+ ( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \
+ wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING ),
+
+ wxTEXT_ATTR_ALIGNMENT = 0x00000080,
+ wxTEXT_ATTR_LEFT_INDENT = 0x00000100,
+ wxTEXT_ATTR_RIGHT_INDENT = 0x00000200,
+ wxTEXT_ATTR_TABS = 0x00000400,
+
+ wxTEXT_ATTR_PARA_SPACING_AFTER = 0x00000800,
+ wxTEXT_ATTR_PARA_SPACING_BEFORE = 0x00001000,
+ wxTEXT_ATTR_LINE_SPACING = 0x00002000,
+ wxTEXT_ATTR_CHARACTER_STYLE_NAME = 0x00004000,
+ wxTEXT_ATTR_PARAGRAPH_STYLE_NAME = 0x00008000,
+ wxTEXT_ATTR_LIST_STYLE_NAME = 0x00010000,
+ wxTEXT_ATTR_BULLET_STYLE = 0x00020000,
+ wxTEXT_ATTR_BULLET_NUMBER = 0x00040000,
+ wxTEXT_ATTR_BULLET_TEXT = 0x00080000,
+ wxTEXT_ATTR_BULLET_NAME = 0x00100000,
+ wxTEXT_ATTR_URL = 0x00200000,
+ wxTEXT_ATTR_PAGE_BREAK = 0x00400000,
+ wxTEXT_ATTR_EFFECTS = 0x00800000,
+ wxTEXT_ATTR_OUTLINE_LEVEL = 0x01000000,
+
+ /*!
+ * Character and paragraph combined styles
+ */
+
+ wxTEXT_ATTR_CHARACTER = \
+ (wxTEXT_ATTR_FONT|wxTEXT_ATTR_FONT_ENCODING|wxTEXT_ATTR_EFFECTS| \
+ wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL),
+
+ wxTEXT_ATTR_PARAGRAPH = \
+ (wxTEXT_ATTR_ALIGNMENT|wxTEXT_ATTR_LEFT_INDENT|wxTEXT_ATTR_RIGHT_INDENT|wxTEXT_ATTR_TABS|\
+ wxTEXT_ATTR_PARA_SPACING_BEFORE|wxTEXT_ATTR_PARA_SPACING_AFTER|wxTEXT_ATTR_LINE_SPACING|\
+ wxTEXT_ATTR_BULLET_STYLE|wxTEXT_ATTR_BULLET_NUMBER|wxTEXT_ATTR_BULLET_TEXT|wxTEXT_ATTR_BULLET_NAME|\
+ wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL),
+
+ wxTEXT_ATTR_ALL = (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH)
+};
/*!
* Styles for wxTextAttr::SetBulletStyle
*/
-
-#define wxTEXT_ATTR_BULLET_STYLE_NONE 0x00000000
-#define wxTEXT_ATTR_BULLET_STYLE_ARABIC 0x00000001
-#define wxTEXT_ATTR_BULLET_STYLE_LETTERS_UPPER 0x00000002
-#define wxTEXT_ATTR_BULLET_STYLE_LETTERS_LOWER 0x00000004
-#define wxTEXT_ATTR_BULLET_STYLE_ROMAN_UPPER 0x00000008
-#define wxTEXT_ATTR_BULLET_STYLE_ROMAN_LOWER 0x00000010
-#define wxTEXT_ATTR_BULLET_STYLE_SYMBOL 0x00000020
-#define wxTEXT_ATTR_BULLET_STYLE_BITMAP 0x00000040
-#define wxTEXT_ATTR_BULLET_STYLE_PARENTHESES 0x00000080
-#define wxTEXT_ATTR_BULLET_STYLE_PERIOD 0x00000100
-#define wxTEXT_ATTR_BULLET_STYLE_STANDARD 0x00000200
-#define wxTEXT_ATTR_BULLET_STYLE_RIGHT_PARENTHESIS 0x00000400
-#define wxTEXT_ATTR_BULLET_STYLE_OUTLINE 0x00000800
-
-#define wxTEXT_ATTR_BULLET_STYLE_ALIGN_LEFT 0x00000000
-#define wxTEXT_ATTR_BULLET_STYLE_ALIGN_RIGHT 0x00001000
-#define wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE 0x00002000
+enum wxTextAttrBulletStyle
+{
+ wxTEXT_ATTR_BULLET_STYLE_NONE = 0x00000000,
+ wxTEXT_ATTR_BULLET_STYLE_ARABIC = 0x00000001,
+ wxTEXT_ATTR_BULLET_STYLE_LETTERS_UPPER = 0x00000002,
+ wxTEXT_ATTR_BULLET_STYLE_LETTERS_LOWER = 0x00000004,
+ wxTEXT_ATTR_BULLET_STYLE_ROMAN_UPPER = 0x00000008,
+ wxTEXT_ATTR_BULLET_STYLE_ROMAN_LOWER = 0x00000010,
+ wxTEXT_ATTR_BULLET_STYLE_SYMBOL = 0x00000020,
+ wxTEXT_ATTR_BULLET_STYLE_BITMAP = 0x00000040,
+ wxTEXT_ATTR_BULLET_STYLE_PARENTHESES = 0x00000080,
+ wxTEXT_ATTR_BULLET_STYLE_PERIOD = 0x00000100,
+ wxTEXT_ATTR_BULLET_STYLE_STANDARD = 0x00000200,
+ wxTEXT_ATTR_BULLET_STYLE_RIGHT_PARENTHESIS = 0x00000400,
+ wxTEXT_ATTR_BULLET_STYLE_OUTLINE = 0x00000800,
+
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_LEFT = 0x00000000,
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_RIGHT = 0x00001000,
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE = 0x00002000
+};
/*!
* Styles for wxTextAttr::SetTextEffects
*/
-
-#define wxTEXT_ATTR_EFFECT_NONE 0x00000000
-#define wxTEXT_ATTR_EFFECT_CAPITALS 0x00000001
-#define wxTEXT_ATTR_EFFECT_SMALL_CAPITALS 0x00000002
-#define wxTEXT_ATTR_EFFECT_STRIKETHROUGH 0x00000004
-#define wxTEXT_ATTR_EFFECT_DOUBLE_STRIKETHROUGH 0x00000008
-#define wxTEXT_ATTR_EFFECT_SHADOW 0x00000010
-#define wxTEXT_ATTR_EFFECT_EMBOSS 0x00000020
-#define wxTEXT_ATTR_EFFECT_OUTLINE 0x00000040
-#define wxTEXT_ATTR_EFFECT_ENGRAVE 0x00000080
-#define wxTEXT_ATTR_EFFECT_SUPERSCRIPT 0x00000100
-#define wxTEXT_ATTR_EFFECT_SUBSCRIPT 0x00000200
+enum wxTextAttrEffects
+{
+ wxTEXT_ATTR_EFFECT_NONE = 0x00000000,
+ wxTEXT_ATTR_EFFECT_CAPITALS = 0x00000001,
+ wxTEXT_ATTR_EFFECT_SMALL_CAPITALS = 0x00000002,
+ wxTEXT_ATTR_EFFECT_STRIKETHROUGH = 0x00000004,
+ wxTEXT_ATTR_EFFECT_DOUBLE_STRIKETHROUGH = 0x00000008,
+ wxTEXT_ATTR_EFFECT_SHADOW = 0x00000010,
+ wxTEXT_ATTR_EFFECT_EMBOSS = 0x00000020,
+ wxTEXT_ATTR_EFFECT_OUTLINE = 0x00000040,
+ wxTEXT_ATTR_EFFECT_ENGRAVE = 0x00000080,
+ wxTEXT_ATTR_EFFECT_SUPERSCRIPT = 0x00000100,
+ wxTEXT_ATTR_EFFECT_SUBSCRIPT = 0x00000200
+};
/*!
* Line spacing values
*/
-
-#define wxTEXT_ATTR_LINE_SPACING_NORMAL 10
-#define wxTEXT_ATTR_LINE_SPACING_HALF 15
-#define wxTEXT_ATTR_LINE_SPACING_TWICE 20
+enum wxTextAttrLineSpacing
+{
+ wxTEXT_ATTR_LINE_SPACING_NORMAL = 10,
+ wxTEXT_ATTR_LINE_SPACING_HALF = 15,
+ wxTEXT_ATTR_LINE_SPACING_TWICE = 20
+};
// ----------------------------------------------------------------------------
// wxTextAttr: a structure containing the visual attributes of a text
const wxString& GetListStyleName() const { return m_listStyleName; }
int GetParagraphSpacingAfter() const { return m_paragraphSpacingAfter; }
int GetParagraphSpacingBefore() const { return m_paragraphSpacingBefore; }
+
+ // TODO: should return the relative wxTextAttr* enumeration values
int GetLineSpacing() const { return m_lineSpacing; }
int GetBulletStyle() const { return m_bulletStyle; }
int GetBulletNumber() const { return m_bulletNumber; }
When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive, wxArchiveEntry, wxArchiveOutputStream
*/
Another call to PutNextEntry() closes the current entry and begins the next.
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive, wxArchiveEntry, wxArchiveInputStream
*/
been reached, i.e. after GetNextEntry() returns NULL and Eof() is true.
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive, @ref overview_archive_generic,
wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier
wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry,
wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
See @ref overview_archive_noseek.
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream,
wxArchiveOutputStream
@endcode
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
*/
/////////////////////////////////////////////////////////////////////////////
// Name: tarstrm.h
-// Purpose: interface of wxTarInputStream
+// Purpose: interface of wxTar* classes
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+/** wxTarEntry::GetTypeFlag() values */
+enum wxTarType
+{
+ wxTAR_REGTYPE = '0', //!< regular file
+ wxTAR_LNKTYPE = '1', //!< hard link
+ wxTAR_SYMTYPE = '2', //!< symbolic link
+ wxTAR_CHRTYPE = '3', //!< character special
+ wxTAR_BLKTYPE = '4', //!< block special
+ wxTAR_DIRTYPE = '5', //!< directory
+ wxTAR_FIFOTYPE = '6', //!< named pipe
+ wxTAR_CONTTYPE = '7' //!< contiguous file
+};
+
+/** Archive Formats (use wxTAR_PAX, it's backward compatible) used by wxTarEntry */
+enum wxTarFormat
+{
+ wxTAR_USTAR, //!< POSIX.1-1990 tar format
+ wxTAR_PAX //!< POSIX.1-2001 tar format
+};
+
+
/**
@class wxTarInputStream
Input stream for reading tar files.
- wxTarInputStream::GetNextEntry returns an
- wxTarEntry object containing the meta-data
- for the next entry in the tar (and gives away ownership). Reading from
- the wxTarInputStream then returns the entry's data. Eof() becomes @true
- after an attempt has been made to read past the end of the entry's data.
- When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
+ wxTarInputStream::GetNextEntry() returns a wxTarEntry object containing the
+ meta-data for the next entry in the tar (and gives away ownership).
+ Reading from the wxTarInputStream then returns the entry's data.
+ wxTarInputStream::Eof() becomes @true after an attempt has been made to read
+ past the end of the entry's data.
+
+ When there are no more entries, wxTarInputStream::GetNextEntry() returns @NULL
+ and sets wxTarInputStream::Eof().
Tar entries are seekable if the parent stream is seekable. In practice this
usually means they are only seekable if the tar is stored as a local file and
is not compressed.
@library{wxbase}
- @category{streams}
+ @category{archive,streams}
- @see @ref overview_wxarcbyname "Looking up an archive entry by name"
+ @see @ref overview_archive_byname
*/
class wxTarInputStream : public wxArchiveInputStream
{
//@{
/**
Constructor. In a Unicode build the second parameter @a conv is
- used to translate fields from the standard tar header into Unicode. It has
- no effect on the stream's data. @a conv is only used for the standard
+ used to translate fields from the standard tar header into Unicode.
+
+ It has no effect on the stream's data. @a conv is only used for the standard
tar headers, any pax extended headers are always UTF-8 encoded.
+
If the parent stream is passed as a pointer then the new filter stream
takes ownership of it. If it is passed by reference then it does not.
*/
//@}
/**
- Closes the current entry. On a non-seekable stream reads to the end of
- the current entry first.
+ Closes the current entry.
+ On a non-seekable stream reads to the end of the current entry first.
*/
bool CloseEntry();
/**
Closes the current entry if one is open, then reads the meta-data for
- the next entry and returns it in a wxTarEntry
- object, giving away ownership. The stream is then open and can be read.
+ the next entry and returns it in a wxTarEntry object, giving away ownership.
+ The stream is then open and can be read.
*/
wxTarEntry* GetNextEntry();
/**
Closes the current entry if one is open, then opens the entry specified
by the @a entry object.
- @a entry should be from the same tar file, and the tar should
- be on a seekable stream.
+
+ @a entry should be from the same tar file, and the tar should be on a
+ seekable stream.
*/
bool OpenEntry(wxTarEntry& entry);
};
/**
@class wxTarClassFactory
- Class factory for the tar archive format. See the base class
- for details.
+ Class factory for the tar archive format.
+ See the base class for details.
@library{wxbase}
- @category{FIXME}
+ @category{archive,streams}
- @see @ref overview_wxarc "Archive formats such as zip", @ref
- overview_wxarcgeneric "Generic archive programming", wxTarEntry, wxTarInputStream, wxTarOutputStream
+ @see @ref overview_archive, @ref overview_archive_generic,
+ wxTarEntry, wxTarInputStream, wxTarOutputStream
*/
class wxTarClassFactory : public wxArchiveClassFactory
{
Output stream for writing tar files.
- wxTarOutputStream::PutNextEntry is used to create
- a new entry in the output tar, then the entry's data is written to the
- wxTarOutputStream. Another call to PutNextEntry() closes the current
- entry and begins the next.
+ wxTarOutputStream::PutNextEntry() is used to create a new entry in the output tar,
+ then the entry's data is written to the wxTarOutputStream.
+ Another call to wxTarOutputStream::PutNextEntry() closes the current entry
+ and begins the next.
@library{wxbase}
@category{streams}
- @see @ref overview_wxarc "Archive formats such as zip", wxTarEntry,
- wxTarInputStream
+ @see @ref overview_archive, wxTarEntry, wxTarInputStream
*/
class wxTarOutputStream : public wxArchiveOutputStream
{
/**
If the parent stream is passed as a pointer then the new filter stream
takes ownership of it. If it is passed by reference then it does not.
+
In a Unicode build the third parameter @a conv is used to translate the
headers fields into an 8-bit encoding. It has no effect on the stream's data.
+
When the @a format is @e wxTAR_PAX, pax extended headers are generated
when any header field will not fit the standard tar header block or if it
uses any non-ascii characters.
+
Extended headers are stored as extra 'files' within the tar, and will be
extracted as such by any other tar program that does not understand them.
The @a conv parameter only affect the standard tar headers, the extended
headers are always UTF-8 encoded.
- When the @a format is @e wxTAR_USTAR, no extended headers are
- generated, and instead a warning message is logged if any header field
- overflows.
+
+ When the @a format is @e wxTAR_USTAR, no extended headers are generated,
+ and instead a warning message is logged if any header field overflows.
*/
wxTarOutputStream(wxOutputStream& stream,
wxTarFormat format = wxTAR_PAX,
//@}
/**
- The destructor calls Close() to finish
- writing the tar if it has not been called already.
+ The destructor calls Close() to finish writing the tar if it has
+ not been called already.
*/
virtual ~wxTarOutputStream();
bool Close();
/**
- Close the current entry. It is called implicitly whenever another new
- entry is created with CopyEntry()
- or PutNextEntry(), or
- when the tar is closed.
+ Close the current entry.
+
+ It is called implicitly whenever another new entry is created with
+ CopyEntry() or PutNextEntry(), or when the tar is closed.
*/
bool CloseEntry();
/**
- See wxArchiveOutputStream::CopyArchiveMetaData.
+ See wxArchiveOutputStream::CopyArchiveMetaData().
For the tar format this function does nothing.
*/
bool CopyArchiveMetaData(wxTarInputStream& s);
/**
- Takes ownership of @a entry and uses it to create a new entry
- in the tar. @a entry is then opened in @a inputStream and its contents
- copied to this stream.
+ Takes ownership of @a entry and uses it to create a new entry in the tar.
+ @a entry is then opened in @a inputStream and its contents copied to this stream.
+
For some other archive formats CopyEntry() is much more efficient than
transferring the data using Read() and Write() since it will copy them
- without decompressing and recompressing them. For tar however it makes
- no difference.
+ without decompressing and recompressing them.
+ For tar however it makes no difference.
+
For tars on seekable streams, @a entry must be from the same tar file
- as @e stream. For non-seekable streams, @a entry must also be the
- last thing read from @e inputStream.
+ as @a inputStream. For non-seekable streams, @a entry must also be the
+ last thing read from @a inputStream.
*/
bool CopyEntry(wxTarEntry* entry, wxTarInputStream& inputStream);
//@{
/**
The tar is zero padded to round its size up to @e BlockingFactor * 512 bytes.
- Defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
- (see the @ref wxtaroutputstream() constructor), as
- specified in the POSIX standards.
+
+ The blocking factor defaults to 10 for @e wxTAR_PAX and 20 for @e wxTAR_USTAR
+ (see wxTarOutputStream()), as specified in the POSIX standards.
*/
- int GetBlockingFactor();
- const void SetBlockingFactor(int factor);
+ int GetBlockingFactor() const;
+ void SetBlockingFactor(int factor);
//@}
/**
- )
- Create a new directory entry
- (see wxArchiveEntry::IsDir)
- with the given name and timestamp.
- PutNextEntry() can
- also be used to create directory entries, by supplying a name with
- a trailing path separator.
+ Create a new directory entry (see wxArchiveEntry::IsDir()) with the given
+ name and timestamp.
+
+ PutNextEntry() can also be used to create directory entries, by supplying
+ a name with a trailing path separator.
*/
- bool PutNextDirEntry(const wxString& name);
+ bool PutNextDirEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now());
- //@{
/**
- , @b wxFileOffset@e size = wxInvalidOffset)
- Create a new entry with the given name, timestamp and size.
+ Takes ownership of entry and uses it to create a new entry in the tar.
*/
bool PutNextEntry(wxTarEntry* entry);
- bool PutNextEntry(const wxString& name);
- //@}
+
+ /**
+ Create a new entry with the given name, timestamp and size.
+ */
+ bool PutNextEntry(const wxString& name, const wxDateTime& dt = wxDateTime::Now(),
+ wxFileOffset size = wxInvalidOffset);
};
Holds the meta-data for an entry in a tar.
+ @section tarentry_fields Field availability
+
+ The tar format stores all the meta-data for an entry ahead of its data,
+ therefore GetNextEntry() always returns a fully populated wxTarEntry object,
+ both when reading from seekable and non-seekable streams.
+
@library{wxbase}
- @category{FIXME}
+ @category{archive,streams}
- @see @ref overview_wxarc "Archive formats such as zip", wxTarInputStream,
- wxTarOutputStream
+ @see @ref overview_archive, wxTarInputStream, wxTarOutputStream
*/
class wxTarEntry : public wxArchiveEntry
{
public:
- //@{
+ /**
+ Constructor.
+
+ The tar archive format stores the entry's size ahead of the entry's data.
+ Therefore when creating an archive on a non-seekable stream it is necessary
+ to supply the correct size when each entry is created.
+ */
+ wxTarEntry(const wxString& name = wxEmptyString,
+ const wxDateTime& dt = wxDateTime::Now(),
+ wxFileOffset size = wxInvalidOffset);
+
/**
Copy constructor.
*/
- wxTarEntry(const wxString& name = wxEmptyString);
wxTarEntry(const wxTarEntry& entry);
- //@}
//@{
/**
- The entry's access time stamp. See also
- wxArchiveEntry::Get/SetDateTime.
+ Gets/sets the entry's access time stamp.
+ See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
*/
- wxDateTime GetAccessTime();
- const void SetAccessTime(const wxDateTime& dt);
+ wxDateTime GetAccessTime() const;
+ void SetAccessTime(const wxDateTime& dt);
//@}
//@{
/**
- The entry's creation time stamp. See also
- wxArchiveEntry::Get/SetDateTime.
+ The entry's creation time stamp.
+ See also wxArchiveEntry::GetDateTime() and wxArchiveEntry::SetDateTime().
*/
- wxDateTime GetCreateTime();
- const void SetCreateTime(const wxDateTime& dt);
+ wxDateTime GetCreateTime() const;
+ void SetCreateTime(const wxDateTime& dt);
//@}
//@{
/**
- OS specific IDs defining a device, these are only meaningful when
- TypeFlag() is set to @e wxTAR_CHRTYPE
- or @e wxTAR_BLKTYPE.
+ OS specific IDs defining a device; these are only meaningful when
+ wxTarEntry::GetTypeFlag() is @e wxTAR_CHRTYPE or @e wxTAR_BLKTYPE.
*/
- int GetDevMajor();
- const int GetDevMinor();
- const void SetDevMajor(int dev);
+ int GetDevMajor() const;
+ int GetDevMinor() const;
+ void SetDevMajor(int dev);
void SetDevMinor(int dev);
//@}
//@{
/**
- The user ID and group ID that has @ref mode() permissions over
- this entry. These values aren't usually useful unless the file will only be
- restored to the same system it originated from. @ref unamegname()
- "Get/SetGroupName and
- Get/SetUserName" can be used instead.
+ The user ID and group ID that has permissions (see wxTarEntry::GetMode())
+ over this entry.
+
+ These values aren't usually useful unless the file will only be
+ restored to the same system it originated from.
+ wxTarEntry::GetGroupName() and wxTarEntry::GetUserName() can be used instead.
*/
- int GetGroupId();
- const int GetUserId();
- const void SetGroupId(int id);
+ int GetGroupId() const;
+ int GetUserId() const;
+ void SetGroupId(int id);
void SetUserId(int id);
//@}
//@{
/**
- The names of the user and group that has @ref mode() permissions
+ The names of the user and group that has permissions (see wxTarEntry::GetMode())
over this entry. These are not present in very old tars.
*/
- wxString GetGroupName();
- const wxString GetUserName();
- const void SetGroupName(const wxString& group);
+ wxString GetGroupName() const;
+ wxString GetUserName() const;
+ void SetGroupName(const wxString& group);
void SetUserName(const wxString& user);
//@}
//@{
/**
The filename of a previous entry in the tar that this entry is a link to.
- Only meaningful when TypeFlag() is set
- to @e wxTAR_LNKTYPE or @e wxTAR_SYMTYPE.
+ Only meaningful when wxTarEntry::GetTypeFlag() is set to @e wxTAR_LNKTYPE
+ or @e wxTAR_SYMTYPE.
*/
- wxString GetLinkName();
- const void SetLinkName(const wxString& link);
+ wxString GetLinkName() const;
+ void SetLinkName(const wxString& link);
//@}
//@{
/**
- UNIX permission bits for this entry. Giving read, write and execute permissions
- to the file's @ref unamegname() "User and Group" and to others.
- Symbols are defined for them in wx/file.h.
+ UNIX permission bits for this entry.
+ Giving read, write and execute permissions to the file's user and group
+ (see GetGroupName() and GetUserName()) and to others.
+
+ The integer is one or more ::wxPosixPermissions flags OR-combined.
*/
- int GetMode();
- const void SetMode(int mode);
+ int GetMode() const;
+ void SetMode(int mode);
//@}
//@{
/**
The size of the entry's data in bytes.
+
The tar archive format stores the entry's size ahead of the entry's data.
Therefore when creating an archive on a non-seekable stream it is necessary to
- supply the correct size when each entry is created. For seekable streams this
- is not necessary as wxTarOutputStream will attempt
+ supply the correct size when each entry is created.
+
+ For seekable streams this is not necessary as wxTarOutputStream will attempt
to seek back and fix the entry's header when the entry is closed, though it is
still more efficient if the size is given beforehand.
*/
- void SetSize(wxFileOffset size) const;
+ void SetSize(wxFileOffset size);
wxFileOffset GetSize() const;
//@}
//@{
/**
- Returns the type of the entry. It should be one of the following:
+ Returns/Sets the type of the entry as a ::wxTarType value.
- When creating archives use just these values. When reading archives
- any other values should be treated as @e wxTAR_REGTYPE.
+ When creating archives use only one of ::wxTarType values.
+ When reading archives, GetTypeFlag() may return a value which does not
+ match any value of ::wxTarType; in this case the returned value should be
+ treated as @e wxTAR_REGTYPE.
*/
- int GetTypeFlag();
- const void SetTypeFlag(int type);
+ int GetTypeFlag() const;
+ void SetTypeFlag(int type);
//@}
- //@{
+ /**
+ Returns the entry's filename in the internal format used within the archive.
+
+ The name can include directory components, i.e. it can be a full path.
+ The names of directory entries are returned without any trailing path separator.
+ This gives a canonical name that can be used in comparisons.
+ */
+ wxString GetInternalName() const;
+
/**
A static member that translates a filename into the internal format used
- within the archive. If the third parameter is provided, the bool pointed
- to is set to indicate whether the name looks like a directory name
- (i.e. has a trailing path separator).
+ within the archive.
+
+ If the third parameter is provided, the bool pointed to is set to indicate
+ whether the name looks like a directory name (i.e. has a trailing path separator).
*/
- wxString GetInternalName();
- const wxString GetInternalName(const wxString& name,
+ static wxString GetInternalName(const wxString& name,
wxPathFormat format = wxPATH_NATIVE,
bool* pIsDir = NULL);
- //@}
/**
Assignment operator.
/**
@class wxTaskBarIcon
- This class represents a taskbar icon. A taskbar icon is an icon that appears in
- the 'system tray' and responds to mouse clicks, optionally with a tooltip above it to help provide information.
+ This class represents a taskbar icon.
+ A taskbar icon is an icon that appears in the 'system tray' and responds to
+ mouse clicks, optionally with a tooltip above it to help provide information.
+
+ @section taskbaricon_xnote X Window System Note
+ Under X Window System, the window manager must support either the
+ @link http://freedesktop.org/wiki/Specifications/systemtray-spec "System Tray Protocol"
+ by freedesktop.org (WMs used by modern desktop environments such as GNOME >= 2,
+ KDE >= 3 and XFCE >= 4 all do) or the older methods used in GNOME 1.2 and KDE 1 and 2.
+
+ If it doesn't, the icon will appear as a toplevel window on user's desktop.
+ Because not all window managers have system tray, there's no guarantee that
+ wxTaskBarIcon will work correctly under X Window System and so the applications
+ should use it only as an optional component of their user interface.
+ The user should be required to explicitly enable the taskbar icon on Unix,
+ it shouldn't be on by default.
+
+ @beginEventTable{wxTaskBarIconEvent}
+ Note that not all ports are required to send these events and so it's better
+ to override wxTaskBarIcon::CreatePopupMenu() if all that the application does
+ is that it shows a popup menu in reaction to mouse click.
+ @event{EVT_TASKBAR_MOVE(func)}
+ Process a wxEVT_TASKBAR_MOVE event.
+ @event{EVT_TASKBAR_LEFT_DOWN(func)}
+ Process a wxEVT_TASKBAR_LEFT_DOWN event.
+ @event{EVT_TASKBAR_LEFT_UP(func)}
+ Process a wxEVT_TASKBAR_LEFT_UP event.
+ @event{EVT_TASKBAR_RIGHT_DOWN(func)}
+ Process a wxEVT_TASKBAR_RIGHT_DOWN event.
+ @event{EVT_TASKBAR_RIGHT_UP(func)}
+ Process a wxEVT_TASKBAR_RIGHT_UP event.
+ @event{EVT_TASKBAR_LEFT_DCLICK(func)}
+ Process a wxEVT_TASKBAR_LEFT_DCLICK event.
+ @event{EVT_TASKBAR_RIGHT_DCLICK(func)}
+ Process a wxEVT_TASKBAR_RIGHT_DCLICK event.
+ @event{EVT_TASKBAR_CLICK(func)}
+ This is a synonym for either EVT_TASKBAR_RIGHT_DOWN or UP depending on
+ the platform, use this event macro to catch the event which should result
+ in the menu being displayed on the current platform.
+ @endEventTable
@library{wxadv}
- @category{FIXME}
+ @category{misc}
*/
class wxTaskBarIcon : public wxEvtHandler
{
/**
This method is called by the library when the user requests popup menu
(on Windows and Unix platforms, this is when the user right-clicks the icon).
+
Override this function in order to provide popup menu associated with the icon.
- If CreatePopupMenu returns @NULL (this happens by default),
- no menu is shown, otherwise the menu is
- displayed and then deleted by the library as soon as the user dismisses it.
+ If CreatePopupMenu() returns @NULL (this happens by default), no menu is shown,
+ otherwise the menu is displayed and then deleted by the library as soon as the
+ user dismisses it.
+
The events can be handled by a class derived from wxTaskBarIcon.
*/
virtual wxMenu* CreatePopupMenu();
/**
- This method is similar to wxWindow::Destroy and can
- be used to schedule the task bar icon object for the delayed destruction: it
- will be deleted during the next event loop iteration, which allows the task bar
+ This method is similar to wxWindow::Destroy and can be used to schedule
+ the task bar icon object for the delayed destruction: it will be deleted
+ during the next event loop iteration, which allows the task bar
icon to process any pending events for it before being destroyed.
*/
void Destroy();
bool IsOk() const;
/**
- Pops up a menu at the current mouse position. The events can be handled by
- a class derived from wxTaskBarIcon.
+ Pops up a menu at the current mouse position.
+ The events can be handled by a class derived from wxTaskBarIcon.
+
+ @note
+ It is recommended to override CreatePopupMenu() callback instead of
+ calling this method from event handler, because some ports (e.g. wxCocoa)
+ may not implement PopupMenu() and mouse click events at all.
*/
virtual bool PopupMenu(wxMenu* menu);
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+
+/**
+ The following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment.
+*/
+enum wxTextAttrAlignment
+{
+ wxTEXT_ALIGNMENT_DEFAULT,
+ wxTEXT_ALIGNMENT_LEFT,
+ wxTEXT_ALIGNMENT_CENTRE,
+ wxTEXT_ALIGNMENT_CENTER = wxTEXT_ALIGNMENT_CENTRE,
+ wxTEXT_ALIGNMENT_RIGHT,
+
+ /** wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented.
+ In future justification may be supported when printing or previewing, only. */
+ wxTEXT_ALIGNMENT_JUSTIFIED
+};
+
+/**
+ The following values are passed in a bitlist to wxTextAttr::SetFlags() to
+ determine what attributes will be considered when setting the attributes for a text control.
+*/
+enum wxTextAttrFlags
+{
+ wxTEXT_ATTR_TEXT_COLOUR = 0x00000001,
+ wxTEXT_ATTR_BACKGROUND_COLOUR = 0x00000002,
+ wxTEXT_ATTR_FONT_FACE = 0x00000004,
+ wxTEXT_ATTR_FONT_SIZE = 0x00000008,
+ wxTEXT_ATTR_FONT_WEIGHT = 0x00000010,
+ wxTEXT_ATTR_FONT_ITALIC = 0x00000020,
+ wxTEXT_ATTR_FONT_UNDERLINE = 0x00000040,
+ wxTEXT_ATTR_FONT_ENCODING = 0x02000000,
+ wxTEXT_ATTR_FONT = \
+ ( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \
+ wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING ),
+
+ wxTEXT_ATTR_ALIGNMENT = 0x00000080,
+ wxTEXT_ATTR_LEFT_INDENT = 0x00000100,
+ wxTEXT_ATTR_RIGHT_INDENT = 0x00000200,
+ wxTEXT_ATTR_TABS = 0x00000400,
+
+ wxTEXT_ATTR_PARA_SPACING_AFTER = 0x00000800,
+ wxTEXT_ATTR_PARA_SPACING_BEFORE = 0x00001000,
+ wxTEXT_ATTR_LINE_SPACING = 0x00002000,
+ wxTEXT_ATTR_CHARACTER_STYLE_NAME = 0x00004000,
+ wxTEXT_ATTR_PARAGRAPH_STYLE_NAME = 0x00008000,
+ wxTEXT_ATTR_LIST_STYLE_NAME = 0x00010000,
+ wxTEXT_ATTR_BULLET_STYLE = 0x00020000,
+ wxTEXT_ATTR_BULLET_NUMBER = 0x00040000,
+ wxTEXT_ATTR_BULLET_TEXT = 0x00080000,
+ wxTEXT_ATTR_BULLET_NAME = 0x00100000,
+ wxTEXT_ATTR_URL = 0x00200000,
+ wxTEXT_ATTR_PAGE_BREAK = 0x00400000,
+ wxTEXT_ATTR_EFFECTS = 0x00800000,
+ wxTEXT_ATTR_OUTLINE_LEVEL = 0x01000000,
+
+ /**
+ Character and paragraph combined styles
+ */
+
+ wxTEXT_ATTR_CHARACTER = \
+ (wxTEXT_ATTR_FONT|wxTEXT_ATTR_FONT_ENCODING|wxTEXT_ATTR_EFFECTS| \
+ wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL),
+
+ wxTEXT_ATTR_PARAGRAPH = \
+ (wxTEXT_ATTR_ALIGNMENT|wxTEXT_ATTR_LEFT_INDENT|wxTEXT_ATTR_RIGHT_INDENT|wxTEXT_ATTR_TABS|\
+ wxTEXT_ATTR_PARA_SPACING_BEFORE|wxTEXT_ATTR_PARA_SPACING_AFTER|wxTEXT_ATTR_LINE_SPACING|\
+ wxTEXT_ATTR_BULLET_STYLE|wxTEXT_ATTR_BULLET_NUMBER|wxTEXT_ATTR_BULLET_TEXT|wxTEXT_ATTR_BULLET_NAME|\
+ wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL),
+
+ wxTEXT_ATTR_ALL = (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH)
+};
+
+/**
+ Styles for wxTextAttr::SetBulletStyle
+*/
+enum wxTextAttrBulletStyle
+{
+ wxTEXT_ATTR_BULLET_STYLE_NONE = 0x00000000,
+ wxTEXT_ATTR_BULLET_STYLE_ARABIC = 0x00000001,
+ wxTEXT_ATTR_BULLET_STYLE_LETTERS_UPPER = 0x00000002,
+ wxTEXT_ATTR_BULLET_STYLE_LETTERS_LOWER = 0x00000004,
+ wxTEXT_ATTR_BULLET_STYLE_ROMAN_UPPER = 0x00000008,
+ wxTEXT_ATTR_BULLET_STYLE_ROMAN_LOWER = 0x00000010,
+ wxTEXT_ATTR_BULLET_STYLE_SYMBOL = 0x00000020,
+
+ /** wxTEXT_ATTR_BULLET_STYLE_BITMAP is unimplemented. */
+ wxTEXT_ATTR_BULLET_STYLE_BITMAP = 0x00000040,
+ wxTEXT_ATTR_BULLET_STYLE_PARENTHESES = 0x00000080,
+ wxTEXT_ATTR_BULLET_STYLE_PERIOD = 0x00000100,
+ wxTEXT_ATTR_BULLET_STYLE_STANDARD = 0x00000200,
+ wxTEXT_ATTR_BULLET_STYLE_RIGHT_PARENTHESIS = 0x00000400,
+ wxTEXT_ATTR_BULLET_STYLE_OUTLINE = 0x00000800,
+
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_LEFT = 0x00000000,
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_RIGHT = 0x00001000,
+ wxTEXT_ATTR_BULLET_STYLE_ALIGN_CENTRE = 0x00002000
+};
+
+/**
+ Styles for wxTextAttr::SetTextEffects().
+
+ Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented.
+*/
+enum wxTextAttrEffects
+{
+ wxTEXT_ATTR_EFFECT_NONE = 0x00000000,
+ wxTEXT_ATTR_EFFECT_CAPITALS = 0x00000001,
+ wxTEXT_ATTR_EFFECT_SMALL_CAPITALS = 0x00000002,
+ wxTEXT_ATTR_EFFECT_STRIKETHROUGH = 0x00000004,
+ wxTEXT_ATTR_EFFECT_DOUBLE_STRIKETHROUGH = 0x00000008,
+ wxTEXT_ATTR_EFFECT_SHADOW = 0x00000010,
+ wxTEXT_ATTR_EFFECT_EMBOSS = 0x00000020,
+ wxTEXT_ATTR_EFFECT_OUTLINE = 0x00000040,
+ wxTEXT_ATTR_EFFECT_ENGRAVE = 0x00000080,
+ wxTEXT_ATTR_EFFECT_SUPERSCRIPT = 0x00000100,
+ wxTEXT_ATTR_EFFECT_SUBSCRIPT = 0x00000200
+};
+
+/**
+ Line spacing values; see wxTextAttr::SetLineSpacing().
+*/
+enum wxTextAttrLineSpacing
+{
+ wxTEXT_ATTR_LINE_SPACING_NORMAL = 10,
+ wxTEXT_ATTR_LINE_SPACING_HALF = 15,
+ wxTEXT_ATTR_LINE_SPACING_TWICE = 20
+};
+
+
+/**
+ Describes the possible return values of wxTextCtrl::HitTest().
+
+ The element names correspond to the relationship between the point asked
+ for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point
+ is before (leftward or upward) it and so on.
+ */
+enum wxTextCtrlHitTestResult
+{
+ /// Indicates that wxTextCtrl::HitTest() is not implemented on this
+ /// platform.
+ wxTE_HT_UNKNOWN = -2,
+
+ /// The point is before the character returned.
+ wxTE_HT_BEFORE,
+
+ /// The point is directly on the character returned.
+ wxTE_HT_ON_TEXT,
+
+ /// The point is below the last line of the control.
+ wxTE_HT_BELOW,
+
+ /// The point is beyond the end of line containing the character returned.
+ wxTE_HT_BEYOND
+};
+
+
/**
@class wxTextAttr
for a range of text in a wxTextCtrl or wxRichTextCtrl.
When setting up a wxTextAttr object, pass a bitlist mask to
- wxTextAttr::SetFlags to indicate which style elements should be changed. As
- a convenience, when you call a setter such as SetFont, the relevant bit
+ wxTextAttr::SetFlags() to indicate which style elements should be changed.
+ As a convenience, when you call a setter such as SetFont, the relevant bit
will be set.
@library{wxcore}
/**
Returns the alignment flags.
- See SetAlignment() for a list of available styles.
+ See ::wxTextAttrAlignment for a list of available styles.
*/
wxTextAttrAlignment GetAlignment() const;
/**
Returns the background colour.
*/
- const wxColour GetBackgroundColour() const;
+ const wxColour& GetBackgroundColour() const;
/**
- Returns a string containing the name of the font associated with the bullet
- symbol.
+ Returns a string containing the name of the font associated with the bullet symbol.
Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
*/
- const wxString GetBulletFont() const;
+ const wxString& GetBulletFont() const;
/**
Returns the standard bullet name, applicable if the bullet style is
wxTEXT_ATTR_BULLET_STYLE_STANDARD.
+
Currently the following standard bullet names are supported:
- @c standard/circle
- @c standard/square
- @c standard/diamond
- @c standard/triangle
+ - @c standard/circle
+ - @c standard/square
+ - @c standard/diamond
+ - @c standard/triangle
+
+ @note
For wxRichTextCtrl users only: if you wish your rich text controls to support
- further bullet graphics, you can derive a
- class from wxRichTextRenderer or wxRichTextStdRenderer, override @c
- DrawStandardBullet and @c EnumerateStandardBulletNames, and
- set an instance of the class using wxRichTextBuffer::SetRenderer.
+ further bullet graphics, you can derive a class from wxRichTextRenderer or
+ wxRichTextStdRenderer, override @c DrawStandardBullet and @c EnumerateStandardBulletNames,
+ and set an instance of the class using wxRichTextBuffer::SetRenderer.
*/
- const wxString GetBulletName() const;
+ const wxString& GetBulletName() const;
/**
Returns the bullet number.
/**
Returns the bullet style.
- See SetBulletStyle() for a list of available styles.
+ See ::wxTextAttrBulletStyle for a list of available styles.
*/
int GetBulletStyle() const;
/**
Creates and returns a font specified by the font attributes in the wxTextAttr
- object. Note that
- wxTextAttr does not store a wxFont object, so this is only a temporary font.
- For greater
- efficiency, access the font attributes directly.
+ object. Note that wxTextAttr does not store a wxFont object, so this is only
+ a temporary font.
+
+ For greater efficiency, access the font attributes directly.
*/
wxFont GetFont() const;
long GetLeftSubIndent() const;
/**
- Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL,
- wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE.
+ Returns the line spacing value, one of ::wxTextAttrLineSpacing values.
*/
int GetLineSpacing() const;
long GetRightIndent() const;
/**
- Returns an array of tab stops, each expressed in tenths of a millimeter. Each
- stop
- is measured from the left margin and therefore each value must be larger than
- the last.
+ Returns an array of tab stops, each expressed in tenths of a millimeter.
+
+ Each stop is measured from the left margin and therefore each value must
+ be larger than the last.
*/
const wxArrayInt GetTabs() const;
const wxColour GetTextColour() const;
/**
- Returns the text effect bits of interest. See SetFlags() for further
- information.
+ Returns the text effect bits of interest.
+ See SetFlags() for further information.
*/
int GetTextEffectFlags() const;
/**
- Returns the text effects, a bit list of styles. See SetTextEffects() for
- details.
+ Returns the text effects, a bit list of styles.
+ See SetTextEffects() for details.
*/
int GetTextEffects() const;
/**
- Returns the URL for the content. Content with wxTEXT_ATTR_URL style
- causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
- generates
- a wxTextUrlEvent when the content is clicked.
+ Returns the URL for the content.
+
+ Content with @a wxTEXT_ATTR_URL style causes wxRichTextCtrl to show a
+ hand cursor over it, and wxRichTextCtrl generates a wxTextUrlEvent
+ when the content is clicked.
*/
const wxString GetURL() const;
*/
bool IsParagraphStyle() const;
- //@{
/**
- Creates a new @c wxTextAttr which is a merge of @a base and
- @a overlay. Properties defined in @a overlay take precedence over those
- in @a base. Properties undefined/invalid in both are undefined in the
- result.
+ Copies all defined/valid properties from overlay to current object.
*/
void Merge(const wxTextAttr& overlay);
+
+ /**
+ Creates a new @c wxTextAttr which is a merge of @a base and @a overlay.
+
+ Properties defined in @a overlay take precedence over those in @a base.
+ Properties undefined/invalid in both are undefined in the result.
+ */
static wxTextAttr Merge(const wxTextAttr& base,
const wxTextAttr& overlay);
- //@}
/**
- Sets the paragraph alignment. These are the possible values for @a alignment:
+ Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values.
- Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification
- may be supported
- when printing or previewing, only.
+ Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented.
+ In future justification may be supported when printing or previewing, only.
*/
void SetAlignment(wxTextAttrAlignment alignment);
/**
Sets the standard bullet name, applicable if the bullet style is
wxTEXT_ATTR_BULLET_STYLE_STANDARD.
- See GetBulletName() for a list
- of supported names, and how to expand the range of supported types.
+
+ See GetBulletName() for a list of supported names, and how
+ to expand the range of supported types.
*/
void SetBulletName(const wxString& name);
void SetBulletNumber(int n);
/**
- Sets the bullet style. The following styles can be passed:
+ Sets the bullet style.
- Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported.
+ The ::wxTextAttrBulletStyle enumeration values are all supported,
+ except for wxTEXT_ATTR_BULLET_STYLE_BITMAP.
*/
void SetBulletStyle(int style);
/**
- Sets the bullet text, which could be a symbol, or (for example) cached outline
- text.
+ Sets the bullet text, which could be a symbol, or (for example) cached
+ outline text.
*/
void SetBulletText(const wxString text);
void SetCharacterStyleName(const wxString& name);
/**
- Sets the flags determining which styles are being specified. The following
- flags can be passed in a bitlist:
+ Sets the flags determining which styles are being specified.
+ The ::wxTextAttrFlags values can be passed in a bitlist.
*/
void SetFlags(long flags);
/**
- Sets the attributes for the given font. Note that wxTextAttr does not store an
- actual wxFont object.
+ Sets the attributes for the given font.
+ Note that wxTextAttr does not store an actual wxFont object.
*/
void SetFont(const wxFont& font);
/**
Sets the left indent and left subindent in tenths of a millimetre.
The sub-indent is an offset from the left of the paragraph, and is used for all
- but the
- first line in a paragraph. A positive value will cause the first line to appear
- to the left
+ but the first line in a paragraph.
+
+ A positive value will cause the first line to appear to the left
of the subsequent lines, and a negative value will cause the first line to be
- indented
- relative to the subsequent lines.
- wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
- the distance between
- the margin and the bullet. The content of the paragraph, including the first
- line, starts
- at leftMargin + leftSubIndent. So the distance between the left edge of the
- bullet and the
+ indented relative to the subsequent lines.
+
+ wxRichTextBuffer uses indentation to render a bulleted item.
+ The left indent is the distance between the margin and the bullet.
+ The content of the paragraph, including the first line, starts
+ at leftMargin + leftSubIndent.
+ So the distance between the left edge of the bullet and the
left of the actual paragraph is leftSubIndent.
*/
void SetLeftIndent(int indent, int subIndent = 0);
/**
Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing,
- 15 means 1.5 spacing, and 20 means double spacing. The following constants are
- defined for convenience:
+ 15 means 1.5 spacing, and 20 means double spacing.
+ The ::wxTextAttrLineSpacing values are defined for convenience.
*/
void SetLineSpacing(int spacing);
void SetListStyleName(const wxString& name);
/**
- Specifies the outline level. Zero represents normal text. At present, the
- outline level is
- not used, but may be used in future for determining list levels and for
- applications
- that need to store document structure information.
+ Specifies the outline level. Zero represents normal text.
+ At present, the outline level is not used, but may be used in future for
+ determining list levels and for applications that need to store document
+ structure information.
*/
void SetOutlineLevel(int level);
void SetTextColour(const wxColour& colText);
/**
- Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS
- to SetFlags().
+ Sets the text effect bits of interest.
+
+ You should also pass wxTEXT_ATTR_EFFECTS to SetFlags().
See SetFlags() for further information.
*/
void SetTextEffectFlags(int flags);
/**
Sets the text effects, a bit list of styles.
- The following styles can be passed:
+ The ::wxTextAttrEffects enumeration values can be used.
Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
are implemented.
+
wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case
- of the actual buffer
- text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text.
+ of the actual buffer text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws
+ a line through text.
+
To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call
- SetTextEffectFlags() with the styles (taken from the
- above set) that you are interested in setting.
+ SetTextEffectFlags() with the styles (taken from the above set) that you
+ are interested in setting.
*/
void SetTextEffects(int effects);
/**
Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this
- style
- causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
- generates
- a wxTextUrlEvent when the content is clicked.
+ style causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
+ generates a wxTextUrlEvent when the content is clicked.
*/
void SetURL(const wxString& url);
void operator operator=(const wxTextAttr& attr);
};
-/**
- Describes the possible return values of wxTextCtrl::HitTest().
-
- The element names correspond to the relationship between the point asked
- for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point
- is before (leftward or upward) it and so on.
- */
-enum wxTextCtrlHitTestResult
-{
- /// Indicates that wxTextCtrl::HitTest() is not implemented on this
- /// platform.
- wxTE_HT_UNKNOWN = -2,
-
- /// The point is before the character returned.
- wxTE_HT_BEFORE,
-
- /// The point is directly on the character returned.
- wxTE_HT_ON_TEXT,
-
- /// The point is below the last line of the control.
- wxTE_HT_BELOW,
-
- /// The point is beyond the end of line containing the character returned.
- wxTE_HT_BEYOND
-};
-
/**
@class wxTextCtrl
capitalized.
@endStyleTable
+ Note that alignment styles (wxTE_LEFT, wxTE_CENTRE and wxTE_RIGHT) can be
+ changed dynamically after control creation on wxMSW and wxGTK. wxTE_READONLY,
+ wxTE_PASSWORD and wrapping styles can be dynamically changed under wxGTK but
+ not wxMSW. The other styles can be only set during control creation.
+
@section textctrl_text_format wxTextCtrl Text Format
wxID_REDO. The associated UI update events are also processed
automatically, when the control has the focus.
- To process input from a text control, use these event handler macros to
- direct input to member functions that take a wxCommandEvent argument.
-
@beginEventTable{wxCommandEvent}
@event{EVT_TEXT(id, func)}
Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text
changes. Notice that this event will be sent when the text controls
contents changes -- whether this is due to user input or comes from the
- program itself (for example, if SetValue() is called); see
- ChangeValue() for a function which does not send this event. This
- event is however not sent during the control creation.
+ program itself (for example, if wxTextCtrl::SetValue() is called); see
+ wxTextCtrl::ChangeValue() for a function which does not send this event.
+ This event is however not sent during the control creation.
@event{EVT_TEXT_ENTER(id, func)}
Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is
pressed in a text control which must have wxTE_PROCESS_ENTER style for
wxGTK2 only currently).
@event{EVT_TEXT_MAXLEN(id, func)}
This event is generated when the user tries to enter more text into the
- control than the limit set by SetMaxLength(), see its description.
+ control than the limit set by wxTextCtrl::SetMaxLength(), see its description.
@endEventTable
@library{wxcore}
class wxTextCtrl : public wxControl
{
public:
- //@{
/**
- Constructor, creating and showing a text control.
- @see Create()
+ Default ctor.
*/
- wxTextCtrl();
+ wxTextCtrl();
/**
Constructor, creating and showing a text control.
@param name
Window name.
- @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be
+ @remarks
+ The horizontal scrollbar (wxHSCROLL style flag) will only be
created for multi-line text controls. Without a horizontal
scrollbar, text lines that don't fit in the control's size will be
- wrapped (but no newline character is inserted). Single line
- controls don't have a horizontal scrollbar, the text is
- automatically scrolled so that the insertion point is always
- visible.
+ wrapped (but no newline character is inserted).
+ Single line controls don't have a horizontal scrollbar, the text is
+ automatically scrolled so that the insertion point is always visible.
@see Create(), wxValidator
*/
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = wxTextCtrlNameStr);
- //@}
/**
Destructor, destroying the text control.
@param text
Text to write to the text control.
- @remarks After the text is appended, the insertion point will be at the
+ @remarks
+ After the text is appended, the insertion point will be at the
end of the text control. If this behaviour is not desired, the
- programmer should use GetInsertionPoint and SetInsertionPoint.
+ programmer should use GetInsertionPoint() and SetInsertionPoint().
@see WriteText()
*/
/**
Sets the text value and marks the control as not-modified (which means
- that IsModified() would return @false immediately after the call to
- SetValue).
+ that IsModified() would return @false immediately after the call to SetValue()).
This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
event but otherwise is identical to SetValue().
- See @ref overview_progevent "this topic" for more information.
+ See @ref overview_eventhandling_prog for more information.
@since 2.7.1
This functions inserts into the control the character which would have
been inserted if the given key event had occurred in the text control.
- The @a event object should be the same as the one passed to @c
- EVT_KEY_DOWN handler previously by wxWidgets. Please note that this
- function doesn't currently work correctly for all keys under any
- platform but MSW.
+ The @a event object should be the same as the one passed to @c EVT_KEY_DOWN
+ handler previously by wxWidgets. Please note that this function doesn't
+ currently work correctly for all keys under any platform but MSW.
@return
- @true if the event resulted in a change to the control, @false
- otherwise.
+ @true if the event resulted in a change to the control, @false otherwise.
*/
virtual bool EmulateKeyPress(const wxKeyEvent& event);
This is defined as the zero based index of the character position to
the right of the insertion point. For example, if the insertion point
is at the end of the single-line text control, it is equal to both
- GetLastPosition() and GetValue().length() (but notice that the latter
+ GetLastPosition() and @c "GetValue().Length()" (but notice that the latter
equality is not necessarily true for multiline edit controls which may
use multiple new line characters).
+
+ The following code snippet safely returns the character at the insertion
+ point or the zero character if the point is at the end of the control.
+
+ @code
+ char GetCurrentChar(wxTextCtrl *tc) {
+ if (tc->GetInsertionPoint() == tc->GetLastPosition())
+ return '\0';
+ return tc->GetValue[tc->GetInsertionPoint()];
+ }
+ @endcode
*/
virtual long GetInsertionPoint() const;
/**
Returns the number of lines in the text control buffer.
- @remarks Note that even empty text controls have one line (where the
- insertion point is), so GetNumberOfLines() never
- returns 0.
+ @remarks
+ Note that even empty text controls have one line (where the
+ insertion point is), so GetNumberOfLines() never returns 0.
+ For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a
+ multi-line text control is calculated by actually counting newline
+ characters in the buffer, i.e. this function returns the number of
+ logical lines and doesn't depend on whether any of them are wrapped.
+ For all the other platforms, the number of physical lines in the
+ control is returned.
+ Also note that you may wish to avoid using functions that work with
+ line numbers if you are working with controls that contain large
+ amounts of text as this function has O(N) complexity for N being
+ the number of lines.
*/
virtual int GetNumberOfLines() const;
/**
Gets the contents of the control.
+
Notice that for a multiline text control, the lines will be separated
by (Unix-style) @c \\n characters, even under Windows where they are
separated by a @c \\r\\n sequence in the native control.
If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
character closest to this position are returned in the @a col and @a
- row parameters (unless the pointers are @NULL which is allowed). Please
- note that this function is currently only implemented in wxUniv, wxMSW
+ row parameters (unless the pointers are @NULL which is allowed).
+ Please note that this function is currently only implemented in wxUniv, wxMSW
and wxGTK2 ports.
@see PositionToXY(), XYToPosition()
virtual bool IsModified() const;
/**
- Returns @true if this is a multi line edit control and @false
- otherwise.
+ Returns @true if this is a multi line edit control and @false otherwise.
@see IsSingleLine()
*/
bool IsMultiLine() const;
/**
- Returns @true if this is a single line edit control and @false
- otherwise.
+ Returns @true if this is a single line edit control and @false otherwise.
- @see @ref IsSingleLine() IsMultiLine
+ @see IsSingleLine(), IsMultiLine()
*/
bool IsSingleLine() const;
virtual void Redo();
/**
- Removes the text starting at the first given position up to (but not
- including) the character at the last position.
+ Removes the text starting at the first given position up to
+ (but not including) the character at the last position.
@param from
The first position.
virtual void Remove(long from, long to);
/**
- Replaces the text starting at the first position up to (but not
- including) the character at the last position with the given text.
+ Replaces the text starting at the first position up to
+ (but not including) the character at the last position with the given text.
@param from
The first position.
If either of the font, foreground, or background colour is not set in
@a style, the values of the previous default style are used for them.
If the previous default style didn't set them neither, the global font
- or colours of the text control itself are used as fall back. However if
- the @a style parameter is the default wxTextAttr, then the default
+ or colours of the text control itself are used as fall back.
+
+ However if the @a style parameter is the default wxTextAttr, then the default
style is just reset (instead of being combined with the new style which
wouldn't change it at all).
into the control.
In other words, it allows to limit the text value length to @a len not
- counting the terminating @c NUL character. If @a len is 0, the
- previously set max length limit, if any, is discarded and the user may
- enter as much text as the underlying native text control widget
- supports (typically at least 32Kb). If the user tries to enter more
- characters into the text control when it already is filled up to the
- maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify
- the program about it (giving it the possibility to show an explanatory
- message, for example) and the extra input is discarded. Note that in
- wxGTK this function may only be used with single line text controls.
+ counting the terminating @c NUL character.
+
+ If @a len is 0, the previously set max length limit, if any, is discarded
+ and the user may enter as much text as the underlying native text control widget
+ supports (typically at least 32Kb).
+ If the user tries to enter more characters into the text control when it
+ already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
+ event is sent to notify the program about it (giving it the possibility
+ to show an explanatory message, for example) and the extra input is discarded.
+
+ Note that in wxGTK this function may only be used with single line text controls.
*/
virtual void SetMaxLength(unsigned long len);
/**
Sets the text value and marks the control as not-modified (which means
- that IsModified() would return @false immediately after the call to
- SetValue).
+ that IsModified() would return @false immediately after the call to SetValue()).
Note that this function generates a @c wxEVT_COMMAND_TEXT_UPDATED
event, to avoid this you can use ChangeValue() instead.
@param text
Text to write to the text control.
- @remarks Newlines in the text string are the only control characters
- allowed, and they will cause appropriate line breaks. See () and
- AppendText() for more convenient ways of writing to the window.
+ @remarks
+ Newlines in the text string are the only control characters
+ allowed, and they will cause appropriate line breaks.
+ See operator<<() and AppendText() for more convenient ways of
+ writing to the window.
+ After the write operation, the insertion point will be at the end
+ of the inserted text, so subsequent write operations will be appended.
+ To append text after the user may have interacted with the control,
+ call wxTextCtrl::SetInsertionPointEnd() before writing.
*/
virtual void WriteText(const wxString& text);
This class can be used to (temporarily) redirect all output sent to a C++
ostream object to a wxTextCtrl instead.
- @note Some compilers and/or build configurations don't support multiply
- inheriting wxTextCtrl from @c std::streambuf in which
- case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM
- option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix,
- specify @c --enable-std_iostreams switch when running configure for this.
+ @note
+ Some compilers and/or build configurations don't support multiply
+ inheriting wxTextCtrl from @c std::streambuf in which case this class is
+ not compiled in.
+ You also must have @c wxUSE_STD_IOSTREAM option on (i.e. set to 1) in your
+ @c setup.h to be able to use it. Under Unix, specify @c --enable-std_iostreams
+ switch when running configure for this.
Example of usage:
This class represents a dialog that requests a one-line password string from
the user.
+
It is implemented as a generic wxWidgets dialog.
@library{wxbase}
@category{cmndlg}
- @see @ref overview_wxpasswordentrydialogoverview "wxPassowrdEntryDialog
- overview"
+ @see @ref overview_cmndlg_password
*/
class wxPasswordEntryDialog : public wxTextEntryDialog
{
public:
+ /**
+ Constructor.
+ Use wxTextEntryDialog::ShowModal to show the dialog.
+
+ @param parent
+ Parent window.
+ @param message
+ Message to show on the dialog.
+ @param defaultValue
+ The default value, which may be the empty string.
+ @param style
+ A dialog style, specifying the buttons (wxOK, wxCANCEL) and an
+ optional wxCENTRE style. You do not need to specify the wxTE_PASSWORD style,
+ it is always applied.
+ @param pos
+ Dialog position.
+ */
+ wxPasswordEntryDialog(wxWindow* parent, const wxString& message,
+ const wxString& caption = "Enter password",
+ const wxString& defaultValue = wxEmptyString,
+ long style = wxOK | wxCANCEL | wxCENTRE,
+ const wxPoint& pos = wxDefaultPosition);
};
/**
@class wxTextEntryDialog
- This class represents a dialog that requests a one-line text string from the
- user.
+ This class represents a dialog that requests a one-line text string from the user.
It is implemented as a generic wxWidgets dialog.
@library{wxbase}
@category{cmndlg}
- @see @ref overview_wxtextentrydialogoverview "wxTextEntryDialog overview"
+ @see @ref overview_cmndlg_textentry
*/
class wxTextEntryDialog : public wxDialog
{
The default value, which may be the empty string.
@param style
A dialog style, specifying the buttons (wxOK, wxCANCEL)
- and an optional wxCENTRE style. Additionally, wxTextCtrl styles (such as
- wxTE_PASSWORD) may be specified here.
+ and an optional wxCENTRE style. Additionally, wxTextCtrl styles
+ (such as wxTE_PASSWORD) may be specified here.
@param pos
Dialog position.
*/
/**
Returns the text that the user has entered if the user has pressed OK, or the
- original value
- if the user has pressed Cancel.
+ original value if the user has pressed Cancel.
*/
wxString GetValue() const;
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+/** The line termination type (kept wxTextFileType name for compability) */
+enum wxTextFileType
+{
+ wxTextFileType_None, //!< incomplete (the last line of the file only)
+ wxTextFileType_Unix, //!< line is terminated with 'LF' = 0xA = 10 = '\n'
+ wxTextFileType_Dos, //!< line is terminated with 'CR' 'LF'
+ wxTextFileType_Mac, //!< line is terminated with 'CR' = 0xD = 13 = '\r'
+ wxTextFileType_Os2 //!< line is terminated with 'CR' 'LF'
+};
+
+
/**
@class wxTextFile
One word of warning: the class is not at all optimized for big files and thus
it will load the file entirely into memory when opened. Of course, you should
- not
- work in this way with large files (as an estimation, anything over 1 Megabyte is
- surely too big for this class). On the other hand, it is not a serious
+ not work in this way with large files (as an estimation, anything over 1 Megabyte
+ is surely too big for this class). On the other hand, it is not a serious
limitation for small files like configuration files or program sources
which are well handled by wxTextFile.
The typical things you may do with wxTextFile in order are:
- Create and open it: this is done with either
- wxTextFile::Create or wxTextFile::Open
- function which opens the file (name may be specified either as the argument to
- these functions or in the constructor), reads its contents in memory (in the
- case of @c Open()) and closes it.
- Work with the lines in the file: this may be done either with "direct
- access" functions like wxTextFile::GetLineCount and
- wxTextFile::GetLine (@e operator[] does exactly the same
- but looks more like array addressing) or with "sequential access" functions
- which include wxTextFile::GetFirstLine/
- wxTextFile::GetNextLine and also
- wxTextFile::GetLastLine/wxTextFile::GetPrevLine.
- For the sequential access functions the current line number is maintained: it is
- returned by wxTextFile::GetCurrentLine and may be
- changed with wxTextFile::GoToLine.
- Add/remove lines to the file: wxTextFile::AddLine and
- wxTextFile::InsertLine add new lines while
- wxTextFile::RemoveLine deletes the existing ones.
- wxTextFile::Clear resets the file to empty.
- Save your changes: notice that the changes you make to the file will @b not be
- saved automatically; calling wxTextFile::Close or doing
- nothing discards them! To save the changes you must explicitly call
- wxTextFile::Write - here, you may also change the line
- termination type if you wish.
+ - Create and open it: this is done with either wxTextFile::Create or wxTextFile::Open
+ function which opens the file (name may be specified either as the argument to
+ these functions or in the constructor), reads its contents in memory (in the
+ case of @c Open()) and closes it.
+ - Work with the lines in the file: this may be done either with "direct
+ access" functions like wxTextFile::GetLineCount and wxTextFile::GetLine
+ (@e operator[] does exactly the same but looks more like array addressing)
+ or with "sequential access" functions which include wxTextFile::GetFirstLine,
+ wxTextFile::GetNextLine and also wxTextFile::GetLastLine, wxTextFile::GetPrevLine.
+ For the sequential access functions the current line number is maintained: it is
+ returned by wxTextFile::GetCurrentLine and may be changed with wxTextFile::GoToLine.
+ - Add/remove lines to the file: wxTextFile::AddLine and wxTextFile::InsertLine
+ add new lines while wxTextFile::RemoveLine deletes the existing ones.
+ wxTextFile::Clear resets the file to empty.
+ - Save your changes: notice that the changes you make to the file will @b not be
+ saved automatically; calling wxTextFile::Close or doing nothing discards them!
+ To save the changes you must explicitly callwxTextFile::Write - here, you may
+ also change the line termination type if you wish.
@library{wxbase}
class wxTextFile
{
public:
+ /**
+ Default constructor, use Create() or Open() with a file name parameter to
+ initialize the object.
+ */
+ wxTextFile();
+
/**
Constructor does not load the file into memory, use Open() to do it.
*/
void Clear() const;
/**
- Closes the file and frees memory, @b losing all changes. Use Write()
- if you want to save them.
+ Closes the file and frees memory, @b "losing all changes".
+ Use Write() if you want to save them.
*/
bool Close() const;
//@{
/**
Creates the file with the given name or the name which was given in the
- @ref ctor() constructor. The array of file lines is initially
- empty.
- It will fail if the file already exists, Open() should
- be used in this case.
+ @ref ctor() constructor. The array of file lines is initially empty.
+
+ It will fail if the file already exists, Open() should be used in this case.
*/
bool Create() const;
- const bool Create(const wxString& strFile) const;
+ bool Create(const wxString& strFile) const;
//@}
/**
/**
Returns the current line: it has meaning only when you're using
GetFirstLine()/GetNextLine() functions, it doesn't get updated when
- you're using "direct access" functions like GetLine(). GetFirstLine() and
- GetLastLine() also change the value of the current line, as well as
- GoToLine().
+ you're using "direct access" functions like GetLine().
+ GetFirstLine() and GetLastLine() also change the value of the current line,
+ as well as GoToLine().
*/
size_t GetCurrentLine() const;
/**
- Get the line termination string corresponding to given constant. @e typeDefault
- is
- the value defined during the compilation and corresponds to the native format
- of the platform, i.e. it will be wxTextFileType_Dos under Windows,
- wxTextFileType_Unix under Unix (including Mac OS X when compiling with the
- Apple Developer Tools) and wxTextFileType_Mac under Mac OS (including
- Mac OS X when compiling with CodeWarrior).
+ Get the line termination string corresponding to given constant.
+
+ @e typeDefault is the value defined during the compilation and corresponds
+ to the native format of the platform, i.e. it will be @c wxTextFileType_Dos
+ under Windows, @c wxTextFileType_Unix under Unix (including Mac OS X when
+ compiling with the Apple Developer Tools) and @c wxTextFileType_Mac under
+ Mac OS (including Mac OS X when compiling with CodeWarrior).
*/
static const char* GetEOL(wxTextFileType type = typeDefault) const;
/**
- This method together with GetNextLine()
- allows more "iterator-like" traversal of the list of lines, i.e. you may
- write something like:
+ This method together with GetNextLine() allows more "iterator-like"
+ traversal of the list of lines, i.e. you may write something like:
+
+ @code
+ wxTextFile file;
+ ...
+ for ( str = file.GetFirstLine(); !file.Eof(); str = file.GetNextLine() )
+ {
+ // do something with the current line in str
+ }
+ // do something with the last line in str
+ @endcode
*/
wxString GetFirstLine() const;
/**
- Gets the last line of the file. Together with
- GetPrevLine() it allows to enumerate the lines
+ Gets the last line of the file.
+
+ Together with GetPrevLine() it allows to enumerate the lines
in the file from the end to the beginning like this:
+
+ @code
+ wxTextFile file;
+ ...
+ for ( str = file.GetLastLine();
+ file.GetCurrentLine() > 0;
+ str = file.GetPrevLine() )
+ {
+ // do something with the current line in str
+ }
+ // do something with the first line in str
+ @endcode
*/
wxString GetLastLine();
/**
- Retrieves the line number @a n from the file. The returned line may be
- modified but you shouldn't add line terminator at the end - this will be done
- by wxTextFile.
+ Retrieves the line number @a n from the file.
+
+ The returned line may be modified but you shouldn't add line terminator
+ at the end - this will be done by wxTextFile.
*/
wxString GetLine(size_t n) const;
size_t GetLineCount() const;
/**
- Get the type of the line (see also wxTextFile::GetEOL)
+ Get the type of the line (see also wxTextFile::GetEOL).
*/
wxTextFileType GetLineType(size_t n) const;
const char* GetName() const;
/**
- Gets the next line (see GetFirstLine() for
- the example).
+ Gets the next line (see GetFirstLine() for the example).
*/
wxString GetNextLine();
wxString GetPrevLine();
/**
- Changes the value returned by GetCurrentLine()
- and used by wxTextFile::GetFirstLine/GetNextLine().
+ Changes the value returned by GetCurrentLine() and used by GetFirstLine()
+ and GetNextLine().
*/
void GoToLine(size_t n) const;
/**
- Guess the type of file (which is supposed to be opened). If sufficiently
- many lines of the file are in DOS/Unix/Mac format, the corresponding value will
- be returned. If the detection mechanism fails wxTextFileType_None is returned.
+ Guess the type of file (which is supposed to be opened).
+
+ If sufficiently many lines of the file are in DOS/Unix/Mac format,
+ the corresponding value will be returned.
+ If the detection mechanism fails @c wxTextFileType_None is returned.
*/
wxTextFileType GuessType() const;
/**
- Insert a line before the line number @e n.
+ Insert a line before the line number @a n.
*/
void InsertLine(const wxString& str, size_t n,
wxTextFileType type = typeDefault) const;
//@{
/**
- )
Open() opens the file with the given name or the name which was given in the
- @ref ctor() constructor and also loads file in memory on
- success. It will fail if the file does not exist,
- Create() should be used in this case.
- The @e conv argument is only meaningful in Unicode build of wxWidgets when
+ @ref ctor() constructor and also loads file in memory on success.
+
+ It will fail if the file does not exist, Create() should be used in this case.
+
+ The @a conv argument is only meaningful in Unicode build of wxWidgets when
it is used to convert the file to wide character representation.
*/
- bool Open() const;
- const bool Open(const wxString& strFile) const;
+ bool Open(const wxMBConv& conv = wxConvAuto()) const;
+ bool Open(const wxString& strFile, const wxMBConv& conv = wxConvAuto()) const;
//@}
/**
void RemoveLine(size_t n) const;
/**
- )
- Change the file on disk. The @a typeNew parameter allows you to change the
- file format (default argument means "don't change type") and may be used to
- convert, for example, DOS files to Unix.
- The @e conv argument is only meaningful in Unicode build of wxWidgets when
+ Change the file on disk.
+
+ The @a typeNew parameter allows you to change the file format
+ (default argument means "don't change type") and may be used to convert,
+ for example, DOS files to Unix.
+
+ The @a conv argument is only meaningful in Unicode build of wxWidgets when
it is used to convert all lines to multibyte representation before writing them
them to physical file.
- Returns @true if operation succeeded, @false if it failed.
+
+ @return
+ @true if operation succeeded, @false if it failed.
*/
- bool Write(wxTextFileType typeNew = wxTextFileType_None) const;
+ bool Write(wxTextFileType typeNew = wxTextFileType_None,
+ const wxMBConv& conv = wxConvAuto()) const;
/**
The same as GetLine().
See @ref overview_archive_noseek.
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive_noseek, wxZipEntry, wxZipInputStream, wxZipOutputStream
*/
- wxZipEntry::IsText
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive, wxZipInputStream, wxZipOutputStream, wxZipNotifier
*/
wxZipInputStream::SeekI() always returns ::wxInvalidOffset.
@library{wxbase}
- @category{streams}
+ @category{archive,streams}
@see @ref overview_archive, wxZipEntry, wxZipOutputStream
*/
See the base class for details.
@library{wxbase}
- @category{archive}
+ @category{archive,streams}
@see @ref overview_archive,
@ref overview_archive_generic,
entry and begins the next.
@library{wxbase}
- @category{streams}
+ @category{archive,streams}
@see @ref overview_archive, wxZipEntry, wxZipInputStream
*/
projects / wxWidgets.git / commitdiff
