wxRuby Documentation Home

# Wx::Document

The document class can be used to model an application’s file-based
data. It is part of the document/view framework supported by Widgets,
and cooperates with the View, DocTemplate and DocManager classes.

## Derived from

EvtHandler

Object

## See also

Document overview, View, DocTemplate, DocManager

## Methods

- Document#m__command_processor
- Document#m__document_file
- Document#m__document_modified
- Document#m__document_template
- Document#m__document_title
- Document#m__document_type_name
- Document#m__document_views
- Document.new
- Document#add_view
- Document#close
- Document#delete_all_views
- Document#get_command_processor
- Document#get_document_template
- Document#get_document_manager
- Document#get_document_name
- Document#get_document_window
- Document#get_filename
- Document#get_first_view
- Document#get_printable_name
- Document#get_title
- Document#get_views
- Document#is_modified
- Document#load_object
- Document#modify
- Document#on_changed_view_list
- Document#on_close_document
- Document#on_create
- Document#on_create_command_processor
- Document#on_new_document
- Document#on_open_document
- Document#on_save_document
- Document#on_save_modified
- Document#remove_view
- Document#save
- Document#save_as
- Document#save_object
- Document#set_command_processor
- Document#set_document_name
- Document#set_document_template
- Document#set_filename
- Document#set_title
- Document#update_all_views

### Document#m__command_processor

CommandProcessor*m_commandProcessor

A pointer to the command processor associated with this document.

### Document#m__document_file

Stringm_documentFile

Filename associated with this document (``" if none).

### Document#m__document_modified

boolm_documentModified

true if the document has been modified, false otherwise.

### Document#m__document_template

DocTemplate *m_documentTemplate

A pointer to the template from which this document was created.

### Document#m__document_title

Stringm_documentTitle

Document title. The document title is used for an associated
frame (if any), and is usually constructed by the framework from
the filename.

### Document#m__document_type_name

Stringm_documentTypeName

The document type name given to the DocTemplate constructor, copied to this
variable when the document is created. If several document templates are
created that use the same document type, this variable is used in DocManager::CreateView
to collate a list of alternative view types that can be used on this kind of
document. Do not change the value of this variable.

### Document#m__document_views

Listm_documentViews

List of View instances associated with this document.

### Document.new

destructor()

Destructor. Removes itself from the document manager.

### Document#add_view

Boolean add_view(%(arg-type)View% view)

If the view is not already in the list of views, adds the view and calls OnChangedViewList.

### Document#close

Boolean close()

Closes the document, by calling OnSaveModified and then (if this returned true) OnCloseDocument.
This does not normally delete the document object: use DeleteAllViews to do this implicitly.

### Document#delete_all_views

Boolean delete_all_views()

Calls View::Close and deletes each view. Deleting the final view will implicitly
delete the document itself, because the View destructor calls RemoveView. This
in turns calls Document::OnChangedViewList, whose default implemention is to
save and delete the document if no views exist.

### Document#get_command_processor

CommandProcessor get_command_processor()

Returns a pointer to the command processor associated with this document.

See CommandProcessor.

### Document#get_document_template

DocTemplate get_document_template()

Gets a pointer to the template that created the document.

### Document#get_document_manager

DocManager get_document_manager()

Gets a pointer to the associated document manager.

### Document#get_document_name

String get_document_name()

Gets the document type name for this document. See the comment for documentTypeName.

### Document#get_document_window

Window get_document_window()

Intended to return a suitable window for using as a parent for document-related
dialog boxes. By default, uses the frame associated with the first view.

### Document#get_filename

String get_filename()

Gets the filename associated with this document, or "" if none is
associated.

### Document#get_first_view

View get_first_view()

A convenience function to get the first view for a document, because
in many cases a document will only have a single view.

See also: get_views

### Document#get_printable_name

get_printable_name(%(arg-type)String% name)

Copies a suitable document name into the supplied name buffer. The default
function uses the title, or if there is no title, uses the filename; or if no
filename, the string unnamed.

### Document#get_title

String get_title()

Gets the title for this document. The document title is used for an associated
frame (if any), and is usually constructed by the framework from
the filename.

### Document#get_views

List get_views()

Returns the list whose elements are the views on the document.

See also: get_first_view

### Document#is_modified

Boolean is_modified()

Returns true if the document has been modified since the last save, false otherwise.
You may need to override this if your document view maintains its own
record of being modified (for example if using TextWindow to view and edit the document).

See also Modify.

### Document#load_object

istream load_object(%(arg-type)istream% stream) InputStream load_object(%(arg-type)InputStream% stream)

Override this function and call it from your own LoadObject before
streaming your own data. LoadObject is called by the framework
automatically when the document contents need to be loaded.

Note that only one of these forms exists, depending on how Widgets
was configured.

### Document#modify

modify(%(arg-type)Boolean% modify)

Call with true to mark the document as modified since the last save, false otherwise.
You may need to override this if your document view maintains its own
record of being modified (for example if using TextWindow to view and edit the document).

See also is_modified.

### Document#on_changed_view_list

on_changed_view_list()

Called when a view is added to or deleted from this document. The default
implementation saves and deletes the document if no views exist (the last
one has just been removed).

### Document#on_close_document

Boolean on_close_document()

The default implementation calls DeleteContents (an empty implementation)
sets the modified flag to false. Override this to
supply additional behaviour when the document is closed with Close.

### Document#on_create

Boolean on_create(%(arg-type)String% path, Integer flags)

Called just after the document object is created to give it a chance
to initialize itself. The default implementation uses the
template associated with the document to create an initial view.
If this function returns false, the document is deleted.

### Document#on_create_command_processor

CommandProcessor on_create_command_processor()

Override this function if you want a different (or no) command processor
to be created when the document is created. By default, it returns
an instance of CommandProcessor.

See CommandProcessor.

### Document#on_new_document

Boolean on_new_document()

The default implementation calls OnSaveModified and DeleteContents, makes a default title for the
document, and notifies the views that the filename (in fact, the title) has changed.

### Document#on_open_document

Boolean on_open_document(%(arg-type)String% filename)

Constructs an input file stream for the given filename (which must not be empty),
and calls LoadObject. If LoadObject returns true, the document is set to
unmodified; otherwise, an error message box is displayed. The document’s
views are notified that the filename has changed, to give windows an opportunity
to update their titles. All of the document’s views are then updated.

### Document#on_save_document

Boolean on_save_document(%(arg-type)String% filename)

Constructs an output file stream for the given filename (which must not be empty),
and calls SaveObject. If SaveObject returns true, the document is set to
unmodified; otherwise, an error message box is displayed.

### Document#on_save_modified

Boolean on_save_modified()

If the document has been modified, prompts the user to ask if the changes should
be changed. If the user replies Yes, the Save function is called. If No, the
document is marked as unmodified and the function succeeds. If Cancel, the
function fails.

### Document#remove_view

Boolean remove_view(%(arg-type)View% view)

Removes the view from the document’s list of views, and calls OnChangedViewList.

### Document#save

Boolean save()

Saves the document by calling OnSaveDocument if there is an associated filename,
or SaveAs if there is no filename.

### Document#save_as

Boolean save_as()

Prompts the user for a file to save to, and then calls OnSaveDocument.

### Document#save_object

ostream save_object(%(arg-type)ostream% stream) OutputStream save_object(%(arg-type)OutputStream% stream)

Override this function and call it from your own SaveObject before
streaming your own data. SaveObject is called by the framework
automatically when the document contents need to be saved.

Note that only one of these forms exists, depending on how Widgets
was configured.

### Document#set_command_processor

set_command_processor(%(arg-type)CommandProcessor% processor)

Sets the command processor to be used for this document. The document will then be responsible
for its deletion. Normally you should not call this; override OnCreateCommandProcessor
instead.

See CommandProcessor.

### Document#set_document_name

set_document_name(%(arg-type)String% name)

Sets the document type name for this document. See the comment for documentTypeName.

### Document#set_document_template

set_document_template(%(arg-type)DocTemplate% templ)

Sets the pointer to the template that created the document. Should only be called by the
framework.

### Document#set_filename

set_filename(%(arg-type)String% filename, Boolean notifyViews = false)

Sets the filename for this document. Usually called by the framework.

If notifyViews is true, View::OnChangeFilename is called for all views.

### Document#set_title

set_title(%(arg-type)String% title)

Sets the title for this document. The document title is used for an associated
frame (if any), and is usually constructed by the framework from
the filename.

### Document#update_all_views

update_all_views(%(arg-type)View% sender = nil, Object hint = nil)

Updates all views. If sender is non-NULL, does not update this view.

hint represents optional information to allow a view to optimize its update.

[This page automatically generated from the Textile source at 2023-06-09 00:45:33 +0000]