nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BFilePanel_Overview.html

311 lines
32 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - System Overview - The Storage Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheStorageKit_Overview.html" title="The Storage Kit" /><link rel="prev" href="BFile_Overview.html" title="BFile" /><link rel="next" href="BMimeType_Overview.html" title="BMimeType" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BFile_Overview.html" title="BFile"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheStorageKit_Overview.html" title="The Storage Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BMimeType_Overview.html" title="BMimeType"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - System Overview - The Storage Kit</div></div><div id="headerB">Prev: <a href="BFile_Overview.html">BFile</a>  Up: <a href="TheStorageKit_Overview.html">The Storage Kit</a>  Next: <a href="BMimeType_Overview.html">BMimeType</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Overview"></a>BFilePanel</h2></div></div></div><a id="id606192" class="indexterm"></a><p>
<code class="classname">BFilePanel</code> knows how to create and display an "Open File" or "Save File"
panel, and provides the means for filtering and responding to the user's
actions on the panel. The Save Panel looks like this:
</p><div class="mediaobject"><img src="./images/TheStorageKit/FilePanel1.png" alt="File Save Panel" /></div><p>
The Open Panel looks pretty much the same, but without the text view in
the lower left corner.
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Creating_Using"></a>Creating and Using a BFilePanel</h3></div></div></div><p>
To create and use a <code class="classname">BFilePanel</code>, follow these steps:
</p><div class="orderedlist"><ol><li><p>
Construct a <code class="classname">BFilePanel</code> object in response to the user's request
(most likely, a click on an "Open" or "Save"/"Save As" menu item). When
you construct the panel, you have to specify its "mode" (Open or Save).
</p></li><li><p>
Fine-tune the panel by telling it which directory to display,
whether it allows multiple selection, whether it can open a directory,
which target it should send notifications to, and so on. (Most of these
parameters can also be set in the constructor.)
</p></li><li><p>
Invoke <code class="methodname">Show()</code> on the panel, and then wait for the user to confirm a
selection (or close the panel).
</p></li><li><p>
Receive a message. When the user confirms a selection (or cancels
the panel), the panel disappears and a notification message (Open, Save,
or Cancel) is sent to the panel's target. The message identifies the
confirmed file(s).
</p></li><li><p>
Delete the <code class="classname">BFilePanel</code> object…or don't. When the user closes a
file panel, the object is not automatically deleted; you have to do it
yourself. But you may not want to. If you don't delete the panel, you can
simply call <code class="methodname">Show()</code> the next time you want to display it; the state from
the previous invocation (the panel's size and location, the directory it
points to) is remembered.
</p></li></ol></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Constructing_Fine_Tuning"></a>Constructing and Fine-tuning the Panel</h3></div></div></div><p>
The <code class="classname">BFilePanel</code> constructor has about two thousand arguments. They all
have default values, and most of the parameters that they control can be
set through individual functions. The following sections list and
describe the constructor arguments and tell you if there's an analogous
function.
</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Panel_Mode"></a>Panel Mode</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type">file_panel_mode</span> <code class="parameter">mode</code></td><td><code class="constant">B_OPEN_PANEL</code></td><td>–</td></tr></tbody></table></div><p>
There are two file panel modes: <code class="constant">B_OPEN_PANEL</code> and <code class="constant">B_SAVE_PANEL</code>. You've got
to make up your mind in the constructor.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Target"></a>Target</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type"><a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>*</span> <code class="parameter">target</code></td><td><code class="varname">be_app_messenger</code></td><td><a class="link" href="BFilePanel.html#BFilePanel_SetTarget" title="SetTarget(), Messenger()"><code class="methodname">SetTarget()</code></a></td></tr></tbody></table></div><p>
The <code class="parameter">target</code> represents the
<a class="link" href="BLooper.html" title="BLooper"><code class="classname">BLooper</code></a>/<a class="link" href="BHandler.html" title="BHandler"><code class="classname">BHandler</code></a>
that will receive the Open, Save, and Cancel messages.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Panel_Directory"></a>Panel Directory</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type">entry_ref*</span> <code class="parameter">panel_directory</code></td><td>cwd</td><td>SetPanelDirectory()</td></tr></tbody></table></div><p>
When a panel is first displayed, it has to show the contents of some
directory; this is called the "panel directory." The panel directory
defaults to the current working directory.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Confirmable_Node_Flavors"></a>Confirmable Node Flavors</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type">uint32</span> <code class="parameter">node_flavors</code></td><td><code class="constant">B_FILE_NODE</code></td><td>–</td></tr></tbody></table></div><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>This parameter applies to Open panels only.</p></div></div></div><p>
There are three node flavors: <code class="constant">B_FILE_NODE</code>, <code class="constant">B_DIRECTORY_NODE</code>, and
<code class="constant">B_SYMLINK_NODE</code>. You combine these constants to declare the flavors that
you want the user to be able to confirm. Before describing the flavor
settings, keep this in mind…
</p><ul class="itemizedlist"><li><p>
Double-clicking a directory in the file list always enters the
directory, regardless of the panel's flavor setting.
</p></li></ul><p>
If you understand the following, you can save yourself some reading:
</p><ul class="itemizedlist"><li><p>
If your app wants to open files only, then stick with the default
(<code class="constant">B_FILE_NODE</code>); the user will be able to confirm files and symlinks to
files. If you want directories as well (for example, a compression app
might want to work on files and directories) then add in
<code class="constant">B_DIRECTORY_NODE</code> (symlinks to directories are okay, as well). If you
only want directories (unusual, but possible), then leave <code class="constant">B_FILE_NODE</code>
out of it.
</p></li></ul><p>
If you're not convinced, read on:
</p><ul class="itemizedlist"><li><p>
If the setting includes <code class="constant">B_FILE_NODE</code> and the user selects and confirms
a file or a symlink to a file, the file (or symlink) is delivered to
your target. If it doesn't include <code class="constant">B_FILE_NODE</code> and the user selects a
file (or symlink to a file), the Open button is disabled.
</p></li><li><p>
If the setting includes <code class="constant">B_DIRECTORY_NODE</code> and the user selects and
Opens (i.e. clicks the Open button) a directory or a symlink to a
directory, the directory (or symlink) is delivered to your target. If
it doesn't include <code class="constant">B_DIRECTORY_NODE</code> and the user Opens a directory (or
symlink to a directory), the directory is entered (the contents of the
directory are displayed in the file list).
</p></li><li><p>
If the setting includes <code class="constant">B_SYMLINK_NODE</code> and the user confirms a
symlink, the symlink is delivered to your target. If it doesn't include
<code class="constant">B_SYMLINK_NODE</code> and the user selects symlink, the panel's response
depends on the inclusion of the other two flavors. Note that including
<code class="constant">B_SYMLINK_NODE</code> is an odd thing to do—it only makes sense if it's
not combined with either of the other two flavors, and even then it
doesn't make much sense.
</p></li></ul><p>
As implied by the here, when the user confirms a symlink (regardless of
the flavor setting), you always receive the symlink itself in the Open
message—you don't get the file or directory it points to.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Multiple_Selection"></a>Multiple Selection</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type">bool</span> <code class="parameter">allow_multiple_selection</code></td><td><code class="constant">true</code></td><td>–</td></tr></tbody></table></div><p>
This parameter determines whether the user is allowed to select more than
one item at a time. Save panels should set this to <code class="constant">false</code>.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Notification_Message"></a>Notification Message</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>*</span> <code class="parameter">message</code></td><td>a default <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a></td><td><a class="link" href="BFilePanel.html#BFilePanel_SetMessage" title="SetMessage()"><code class="methodname">SetMessage()</code></a></td></tr></tbody></table></div><p>
By default, the format of the message that's sent to your target when the
user confirms or cancels is defined by the file panel (the default
formats are defined later). You can override the default by specifying
your own <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>.
The <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
is copied by the <code class="classname">BFilePanel</code> object. You
can change this message using the
<a class="link" href="BFilePanel.html#BFilePanel_SetMessage" title="SetMessage()"><code class="methodname">SetMessage()</code></a> function.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Ref_Filter"></a>Ref Filter</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type"><a class="link" href="BRefFilter.html" title="BRefFilter"><code class="classname">BRefFilter</code></a>*</span> <code class="parameter">filter</code></td><td><code class="constant">NULL</code></td><td><a class="link" href="BFilePanel.html#BFilePanel_SetRefFilter" title="SetRefFilter(), RefFilter()"><code class="methodname">SetRefFilter()</code></a></td></tr></tbody></table></div><p>
When panel directory changes (this includes when the panel is
constructed, and when the panel's
<a class="link" href="BFilePanel.html#BFilePanel_Refresh" title="Refresh()"><code class="methodname">Refresh()</code></a> function is called), or when
a new entry is added to the existing directory, the new entries are
passed, one-by-one, to the panel's
<a class="link" href="BRefFilter.html" title="BRefFilter"><code class="classname">BRefFilter</code></a> object through a
<a class="link" href="BRefFilter.html" title="BRefFilter"><code class="classname">BRefFilter</code></a>
hook function. In your implementation of the hook function, you can
reject individual entries; rejected entries won't be displayed in the
file list.
</p><p>
By default, a file panel has no
<a class="link" href="BRefFilter.html" title="BRefFilter"><code class="classname">BRefFilter</code></a>.
To supply one, you have to subclass
<a class="link" href="BRefFilter.html" title="BRefFilter"><code class="classname">BRefFilter</code></a>
(in order to implement the hook function) and pass it in.
</p><ul class="itemizedlist"><li><p>
Note that the ref filter isn't asked to "re-review" the entry list
when the file panel is Show()'d after being hidden.
</p></li></ul></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Is_Modal"></a>Is Modal?</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type">bool</span></td><td><code class="constant">false</code></td><td>–</td></tr></tbody></table></div><p>
A modal file panel can't be closed; to get rid of the panel, the user has
to click a button. By default, file panels are not modal.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Hide_When_Done"></a>Hide When Done</h4></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Argument</th><th>Default</th><th>Function</th></tr></thead><tbody><tr><td><span class="type">bool</span> <code class="parameter">hide_when_done</code></td><td><code class="constant">true</code></td><td><a class="link" href="BFilePanel.html#BFilePanel_SetHideWhenDone" title="SetHideWhenDone(), HidesWhenDone()"><code class="methodname">SetHideWhenDone()</code></a></td></tr></tbody></table></div><p>
By default, a file panel is hidden when the user confirms or Cancels. If
you set <code class="parameter">hide_when_done</code> to <code class="constant">false</code>, the panel remains on the screen.
Clicking the panel's close box always hides the panel
</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_The_Target_And_The_Messages"></a>The Target and the Messages it Sees</h3></div></div></div><p>
When the user confirms a selection or cancels a file panel, a
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> is
constructed and sent to the target of the <code class="classname">BFilePanel</code> object. By default,
the target is
<a class="link" href="BApplication.html#BApplication_be_app_messenger" title="be_app_messenger"><code class="varname">be_app_messenger</code></a>.
You can specify a different target (as a
<a class="link" href="BMessenger.html" title="BMessenger"><code class="classname">BMessenger</code></a>)
through the <code class="classname">BFilePanel</code> constructor, or through the
<a class="link" href="BFilePanel.html#BFilePanel_SetTarget" title="SetTarget(), Messenger()"><code class="methodname">SetTarget()</code></a> function.
</p><p>
The format of the <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
that the target receives depends on whether
the user is opening, saving, or canceling.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Open_Notification"></a>Open Notification</h3></div></div></div><p>
If the target is
<a class="link" href="BApplication.html#BApplication_be_app_messenger" title="be_app_messenger"><code class="varname">be_app_messenger</code></a>
and the <a class="link" href="BMessage.html#BMessage_what" title="what"><code class="varname">what</code></a> field is <code class="constant">B_REFS_RECEIVED</code>,
the <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
shows up in the
<a class="link" href="BApplication.html#BApplication_RefsReceived" title="RefsReceived()"><code class="methodname">RefsReceived()</code></a>
function. Otherwise it's sent to the target's
<a class="link" href="BHandler.html#BHandler_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code></a>.
</p><ul class="itemizedlist"><li><p>
By default, the <a class="link" href="BMessage.html#BMessage_what" title="what"><code class="varname">what</code></a>
field is <code class="constant">B_REFS_RECEIVED</code>. You can override the
default by supplying your own
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
(<a class="link" href="BFilePanel.html#BFilePanel_SetMessage" title="SetMessage()"><code class="methodname">SetMessage()</code></a>).
</p></li><li><p>
The <code class="varname">refs</code> field (type <code class="constant">B_REF_TYPE</code>) contains
<span class="type">entry_ref</span> structures, one
for each entry that the user has confirmed.
</p></li><li><p>
The message may contain other fields, as copied from the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> you
(optionally) supplied. The data in these fields won't be changed.
</p></li></ul><p>
Keep in mind that the refs that you receive through this message point to
the literal entries that the user confirmed. In other words, if the
confirmed selection is a symlink to a file, you'll receive a ref for the
symlink, not the file (and similarly for a link to a directory). It's up
to you to turn the symlink into a file (which is probably what you want).
</p><p>
If you want a
<a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a>
object, all you have to do is pass <code class="constant">true</code> as the
<code class="parameter">traverse</code> argument to
<a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a>'s
constructor or <a class="link" href="BEntry.html#BEntry_SetTo"><code class="methodname">SetTo()</code></a>:
</p><pre class="programlisting example cpp"><span class="comment">/* We'll assume that 'ref' was just plucked from an
open notification. */</span>
<code class="classname">BEntry</code> <code class="varname">entry</code>(<code class="varname">ref</code>, <code class="constant">true</code>);</pre><p>
You don't even have to check to see if the ref is a symlink.
</p><p>
If you want to turn a symlink ref into a ref to the pointed-to file, just
add this line:
</p><pre class="programlisting example cpp"><code class="varname">entry</code>.<code class="methodname">GetRef</code>(&amp;<code class="varname">ref</code>);</pre></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Save_Notification"></a>Save Notification</h3></div></div></div><p>
Save notifications are always sent to the target's
<a class="link" href="BHandler.html#BHandler_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code></a>
function.
</p><ul class="itemizedlist"><li><p>
By default, the <a class="link" href="BMessage.html#BMessage_what" title="what"><code class="varname">what</code></a>
field is <code class="constant">B_SAVE_REQUESTED</code>. You can override the
default by supplying your own
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
(<a class="link" href="BFilePanel.html#BFilePanel_SetMessage" title="SetMessage()"><code class="methodname">SetMessage()</code></a>).
</p></li><li><p>
The <code class="varname">directory</code> field (type <code class="constant">B_REF_TYPE</code>)
contain a single <span class="type">entry_ref</span>
structure that points to the directory in which the user has requested
the entry be saved (in other words, the ref refers to the panel
directory).
</p></li><li><p>
The <code class="varname">name</code> field (<code class="constant">B_STRING_TYPE</code>) is the text the user typed in the
Save Panel's text view.
</p></li><li><p>
The message may contain other fields, as copied from the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> you
(optionally) supplied. The data in these fields won't be changed.
</p></li></ul><p>
Note that if the user confirms a name that collides with an existing
file, an alert is automatically displayed. The user can then back out of
the confirmation and return to the Save Panel, or clobber the existing
file. The save notification is sent after (and only if) the user agrees
to clobber the file.
</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>The file <span class="emphasis"><em>isn't</em></span> clobbered by the system; it's up to you (as the receiver
of the save notification) to do the dirty work.</p></div></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Cancel_Notification"></a>Cancel Notification</h3></div></div></div><p>
A cancel notification is sent <span class="emphasis"><em>whenever</em></span> the file panel is hidden. This
includes the Cancel button being clicked, the panel being closed, and the
panel being hidden after an open or a save (given that the panel is in
hide-when-done mode).
</p><p>
Cancel notifications are always sent to the target's
<a class="link" href="BHandler.html#BHandler_MessageReceived" title="MessageReceived()"><code class="methodname">MessageReceived()</code></a>
function.
</p><ul class="itemizedlist"><li><p>
The <a class="link" href="BMessage.html#BMessage_what" title="what"><code class="varname">what</code></a>
field is always <code class="constant">B_CANCEL</code>, even if you supplied your own
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>.
</p></li><li><p>
The <code class="varname">old_what</code> field (<code class="constant">B_UINT32_TYPE</code>) records the "previous" what
value. This is only useful (and dependable) if you supplied your own
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>:
The <a class="link" href="BMessage.html#BMessage_what" title="what"><code class="varname">what</code></a>
from your message is moved to the <code class="varname">old_what</code> field.
If you didn't supply a <a class="link" href="BMessage.html#BMessage_what" title="what"><code class="varname">what</code></a>,
you should ignore this field (it could contain garbage).
</p></li><li><p>
The <code class="varname">source</code> (<code class="constant">B_POINTER_TYPE</code>) is a
pointer to the <code class="classname">BFilePanel</code> object
that was closed.
</p></li><li><p>
The message may contain other fields, as copied from the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>: you
(optionally) supplied. The data in these fields won't be changed.
</p></li></ul><p>
Keep in mind that when a file panel is closed—regardless of how
it's closed—the <code class="classname">BFilePanel</code> object is not destroyed. It's merely
hidden.
</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Modifying_The_Look"></a>Modifying the Look of the File Panel</h3></div></div></div><p>
There are two ways you can modify the look of your
<code class="classname">BFilePanel</code> object.
</p><ul class="itemizedlist"><li><p>
You can do some simple text twiddling by calling the label- and
text-setting functions SetButtonLabel() and SetSaveText().
</p></li><li><p>
If you need to really change the look, you can get a handle on the
panel's BWindow and BView objects in order to move them around, add
your own, or whatever. You get the window through the Window()
function. Finding specific views within the window is described below.
</p></li></ul><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Finding_Views"></a>Finding Views in the Panel</h4></div></div></div><p>
The views in the panel are (mostly) named, as listed and shown below
</p><ul class="itemizedlist"><li><p>
"MenuBar" is the window's menu bar.
</p></li><li><p>
"DirMenuField" is the path popup.
</p></li><li><p>
"TitleView" is the bar that holds the attribute titles.
</p></li><li><p>
"PoseView" is the scrollable list of files.
</p></li><li><p>
"VScrollBar" and "HScrollBar" are the vertical and horizontal scroll
bars.
</p></li><li><p>
"CountVw" is the item counter to the left of the horizontal scroll
bar.
</p></li><li><p>
"text view" is where the user types a file name (Save Panel only).
</p></li><li><p>
"default button" is the Save or Open button.
</p></li><li><p>
"cancel button" is the Cancel button.
</p></li></ul><div class="mediaobject"><img src="./images/TheStorageKit/FilePanel2.png" alt="File Panel Views" /></div><p>
The background view doesn't have a name, but it's always the first in the
window's list of views:
</p><pre class="programlisting example cpp"><code class="classname">BView</code>* <code class="varname">background</code> = <code class="varname">filepanel</code>-&gt;<code class="methodname">Window()</code>-&gt;<code class="methodname">ChildAt</code>(0);</pre><p>
The other views can be found by name, reckoning off of the background
view. For example, here we get the "PoseView" view (the view that
contains the file list):
</p><pre class="programlisting example cpp"><code class="classname">BView</code>* <code class="varname">files</code> = <code class="varname">background</code>-&gt;<code class="methodname">FindView</code>("PoseView");</pre></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BFilePanel_Functions"></a>The C Functions</h3></div></div></div><p>
You can also display Open and Save Panels through the global C functions
<code class="function">run_open_panel()</code> and
<code class="function">run_save_panel()</code> (which are declared in
<code class="filename">FilePanel.h</code>). The functions create
<code class="classname">BFilePanel</code> objects using the default
constructor settings (modulo the <span class="type">file_panel_mode</span>, of course).
</p><p>
The C functions create a new file panel each time they're called, and
delete the panel when the user is finished with it.
</p></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BFile_Overview.html">BFile</a>  Up: <a href="TheStorageKit_Overview.html">The Storage Kit</a>  Next: <a href="BMimeType_Overview.html">BMimeType</a> </div><div id="footerB"><div id="footerBL"><a href="BFile_Overview.html" title="BFile"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheStorageKit_Overview.html" title="The Storage Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BMimeType_Overview.html" title="BMimeType"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink