2008-05-19 Cosimo Cecchi <cosimoc@gnome.org>
* docs/Makefile.am:
* docs/nautilus-connect-server.1:
* docs/nautilus-file-management-properties.1:
* docs/nautilus.1:
Adds manpages taken from the Debian package. Many thanks to the
Debian doc authors for these and for making them available
under the GPL license. (#310473 and #501698).
svn path=/trunk/; revision=14180
2003-06-08 Dave Camp <dave@ximian.com>
* src/file-manager/fm-directory-view.c:
(add_bonobo_menu_ui_and_verbs): Allow the context menu to supply
an icon.
2003-05-05 Alexander Larsson <alexl@redhat.com>
* src/nautilus-shell-ui.xml:
Make Go to CD burner a command
* src/nautilus-window-menus.c (nautilus_window_initialize_menus_part_1):
Hide Go to CD burner if burn: not availible.
* docs/style-guide.html:
Clarify the change. We still have to declare variables at the
beginning of a block.
2003-04-23 Alexander Larsson <alexl@redhat.com>
* src/file-manager/fm-list-view.c (key_press_callback):
* libnautilus-private/nautilus-icon-container.c (key_press_event):
* docs/key_mouse_navigation.txt (Keyboard):
Bring up context menu is Ctrl-F10, not Shift-F9
2003-03-27 Alexander Larsson <alexl@redhat.com>
* docs/key_mouse_navigation.txt:
Update keynav docs.
* libnautilus-private/nautilus-icon-private.h:
* libnautilus-private/nautilus-icon-container.c:
(button_release_event), (motion_notify_event), (key_press_event),
(handle_icon_button_press), (has_multiple_selection),
(has_selection):
Don't do context menu on middle button.
Shift-F10 gives directory context menu if no selection
Change Ctrl-F10 to Shift-F9 to pop up directory context menu. Ctrl-F10 was
conflicting with Toolbar keynav.
* src/nautilus-shell-ui.xml:
Remove Escape accelerator for escape. It was colliding with various
other uses of escape all over. Need to rethink this.
2003-03-26 Alexander Larsson <alexl@redhat.com>
* libnautilus-private/nautilus-icon-container.c (handle_icon_button_press):
Re-Fix Home/End.
Make Ctrl-space create a keyboar focus if none exists instead of activating
the selection.
* docs/Makefile.am:
* docs/key_mouse_navigation.txt:
Add some key/mouse docs for views.
2002-11-10 James Willcox <jwillcox@gnome.org>
* docs/nautilus-context-menus.txt:
* libnautilus-private/nautilus-mime-actions.c:
(nautilus_mime_get_popup_components_for_file):
Fixed a slight bug in the context menu query code, and added a bit of
documentation.
* libnautilus-private/nautilus-file-operations.c:
(handle_transfer_ok): Do fix based on patch from Martin Wehner
<mwehner@tfh-berlin.de> to prevent cancel of emptying trash or
deleting from core dumping.
* Makefile.am:
* configure.in:
* docs/.cvsignore:
* docs/Makefile.am:
Add files in the docs directory to tarball.
* libnautilus/nautilus-view-standard-main.c:
(nautilus_view_standard_main_multi): Whitespace tweak.
2001-08-21
Darin Adler <darin@bentspoon.com>
The Nautilus shell, and the file manager inside it, does a lot of
I/O. Because of this, there are some special disciplines required when
writing Nautilus code.
No I/O on the main thread
To be able to respond to the user quickly, Nautilus needs to be
designed so that the main user input thread does not block. The basic
approach is to never do any disk I/O on the main thread.
In practice, Nautilus code does assume that some disk I/O is fast, in
some cases intentionally and in other cases due to programmer
sloppiness. The typical assumption is that reading files from the
user's home directory and the installed files in the Nautilus datadir
are very fast, effectively instantaneous.
So the general approach is to allow I/O for files that have file
system paths, assuming that the access to these files is fast, and to
prohibit I/O for files that have arbitrary URIs, assuming that access
to these could be arbitrarily slow. Although this works pretty well,
it is based on an incorrect assumption, because with NFS and other
kinds of abstract file systems, there can be arbitrarily slow parts of
the file system that have file system paths.
For historical reasons, threading in Nautilus is done through the
gnome-vfs asynchronous I/O abstraction rather than using threads
directly. This means that all the threads are created by gnome-vfs,
and Nautilus code runs on the main thread only. Thus, the rule of
thumb is that synchronous gnome-vfs operations, like the ones in
<libgnomevfs/gnome-vfs-ops.h> are illegal in most Nautilus
code. Similarly, it's illegal to ask for a piece of information, say a
file size, and then wait until it arrives. The program's main thread
must be allowed to get back to the main loop and start asking for user
input again.
How NautilusFile is used to do this
The NautilusFile class presents an API for scheduling this
asynchronous I/O, and dealing with the uncertainty of when the
information will be available. (It also does a few other things, but
that's the main service it provides.) When you want information about
a particular file or directory, you get the NautilusFile object for
that item, using the nautilus_file_get. This operation, like most
NautilusFile operations, is not allowed to do any disk I/O. Once you
have a NautilusFile object, you can ask it questions like "What is
your file type?" by calling functions like
nautilus_file_get_file_type. However, in a newly created NautilusFile
object, the answer is almost certainly "I don't know." Each function
defines a default, which is the answer given for "I don't know." For
example, nautilus_file_get_type will return
GNOME_VFS_FILE_TYPE_UNKNOWN if it doesn't yet know the type.
It's worth taking a side trip to discuss the nature of the
NautilusFile API. Since these classes are a private part of the
Nautilus implementation, we make no effort to have the API be
"complete" in an abstract sense. Instead we add operations as
necessary and give them the semantics that are most handy for our
purposes. For example, we could have a nautilus_file_get_size that
returns a special distinguishable value to mean "I don't know" or a
separate boolean instead of returning 0 for files where the size is
unknown. This is entirely motivated by pragmatic concerns. The intent
is that we tweak these calls as needed if the semantics aren't good
enough.
Back to the newly created NautilusFile object. If you actually need to
get the type, you need to arrange for that information to be fetched
from the file system. There are two ways to make this request. If you
are planning to display the type on an ongoing basis, then you want to
tell the NautilusFile that you'll be monitoring the type and want to
know about changes to it. If you just need one-time information about
the type then you'll want to be informed when the type is
discovered. The calls used for this are nautilus_file_monitor_add and
nautilus_file_call_when_ready respectively. Both of these calls take a
list of information needed about a file. If all you need is the file
type, for example, you would pass a list containing just
NAUTILUS_FILE_ATTRIBUTE_FILE_TYPE (the attributes are defined in
nautilus-file-attributes.h). Not every call has a corresponding file
attribute type. We add new ones as needed.
If you do a nautilus_file_monitor_add, you also typically connect to
the NautilusFile object's changed signal. Each time any monitored
attribute changes, a changed signal is emitted. The caller typically
caches the value of the attribute that was last seen (for example,
what's displayed on screen) and does a quick check to see if the
attribute it cares about has changed. If you do a
nautilus_file_call_when_ready, you don't typically need to connect to
the changed signal, because your callback function will be called when
and if the requested information is ready.
Both a monitor and a call when ready can be cancelled. For ease of
use, neither call requires that you store an ID for
canceling. Instead, the monitor function uses an arbitrary client
pointer, which can be any kind of pointer that's known to not conflict
with other monitorers. Usually, this is a pointer to the monitoring
object, but it can also be, for example, a pointer to a global
variable. The call_when_ready function uses the callback and callback
data to identify the particular callback. One advantage of the monitor
API is that it also lets the NautilusFile framework know that the file
should be monitored for changes made outside Nautilus. This is how we
know when to ask FAM to monitor a file for us.
Lets review a few of the concepts:
1) Nearly all NautilusFile operations, like nautilus_file_get_type,
are not allowed to do any disk I/O.
2) To cause the actual I/O to be done, callers need to use either a
monitor or a call when ready.
3) The actual I/O is done by asynchronous gnome-vfs calls, and this is
done on another thread.
When working with an entire directory of files at once, you work with
a NautilusDirectory object. With the NautilusDirectory object you can
monitor a whole set of NautilusFile objects at once, and you can
connect to a single "files_changed" signal that gets emitted whenever
files within the directory are modified. That way you don't have to
connect separately to each file you want to monitor. These calls are
also the mechanism for finding out which files are in a directory. In
most other respects, they are like the NautilusFile calls.
Caching, the good and the bad
Another feature of the NautilusFile class is the caching. If you keep
around a NautilusFile object, it keeps around information about the
last known state of that file. Thus, if you call
nautilus_file_get_type, you might well get file type of the file found
at this location the last time you looked, rather than the information
about what the file type is now, or "unknown". There are some problems
with this, though.
The first problem is that if wrong information is cached, you need
some way to "goose" the NautilusFile object and get it to grab new
information. This is trickier than it might sound, because we don't
want to constantly distrust information we received just moments
before. To handle this, we have the
nautilus_file_invalidate_attributes and
nautilus_file_invalidate_all_attributes calls, as well as the
nautilus_directory_force_reload call. If some code in Nautilus makes a
change to a file that's known to affect the cached information, it can
call one of these to inform the NautilusFile framework. Changes that
are made through the framework itself are automatically understood, so
usually these calls aren't necessary.
The second problem is that it's hard to predict when information will
and won't be cached. The current rule that's implemented is that no
information is cached if no one retains a reference to the
NautilusFile object. This means that someone else holding a
NautilusFile object can subtly affect the semantics of whether you
have new data or not. Calling nautilus_file_call_when_ready or
nautilus_file_monitor_add will not invalidate the cache, but rather
will return you the already cached information.
These problems are less pronounced when FAM is in use. With FAM, any
monitored file is highly likely to have accurate information, because
changes to the file will be noticed by FAM, and that in turn will
trigger new I/O to determine what the new status of the file is.
Operations that change the file
You'll note that up until this point, I've only discussed getting
information about the file, not making changes to it. NautilusFile
also contains some APIs for making changes. There are two kinds of
these.
The calls that change metadata are an example of the first kind. These
calls make changes to the internal state right away, and schedule I/O
to write the changes out to the file system. There's no way to detect
if the I/O succeeds or fails, and as far as the client code is
concerned, the change takes place right away.
The calls that make other kinds of file system change are an example
of the second kind. These calls take a
NautilusFileOperationCallback. They are all cancellable, and they give
the callback when the operation completes, whether it succeeds or
fails.
Icons
The current implementation of the Nautilus icon factory uses
synchronous I/O to get the icons and ignores these guidelines. The
only reason this doesn't ruin the Nautilus user experience is that it
also refuses to even try to fetch icons from URIs that don't
correspond to file system paths, which for most cases means it limits
itself to reading from the high-speed local disk. Don't ask me what
the repercussions of this are for NFS; do the research and tell me
instead!
Slowness caused by asynchronous operations
The danger in all this asynchronous I/O is that you might end up doing
lots of user interface tasks twice. If you go to display a file right
after asking for information about it, you might immediately show an
"unknown file type" icon. Then, milliseconds later, you may complete
the I/O and discover more information about the file, including the
appropriate icon. So you end up drawing everything twice. There are a
number of strategies for preventing this problem. One of them is to
allow a bit of hysteresis, and wait some fixed amount of time after
requesting the I/O before displaying the "unknown" state. [What
strategy is used in Nautilus right now?]
How to make Nautilus slow
If you add I/O to the functions in NautilusFile that are used simply
to fetch cached file information, you can make Nautilus incredibly I/O
intensive. On the other hand, the NautilusFile API does not provide a
way to do arbitrary file reads, for example. So it can be tricky to
add features to Nautilus, since you first have to educate NautilusFile
about how to do the I/O asynchronously and cache it, then request the
information and have some way to deal with the time when it's not yet
known.
Adding new kinds of I/O usually involves working on the Nautilus I/O
state machine in nautilus-directory-async.c. If we changed Nautilus to
use threading instead of using gnome-vfs asychronous operations, I'm
pretty sure that most of the changes would be here in this
file. That's because the external API used for NautilusFile wouldn't
really have a reason to change. In either case, you'd want to schedule
work to be done, and get called back when the work is complete.
[We probably need more about nautilus-directory-async.c here.]
That's all for now
This is a very rough early draft of this document. Let me know about
other topics that would be useful to be covered in here.
-- Darin
* components/help/converters/gnome-db2html2/sect-elements.c:
(sect_article_end_element), (sect_inlinegraphic_start_element):
* components/help/converters/gnome-db2html2/toc-elements.c:
(toc_sect_end_element):
* components/mozilla/mozilla-events.cpp:
* components/mozilla/nautilus-mozilla-content-view.c:
(make_full_uri_from_relative), (eazel_services_scheme_translate):
* components/music/nautilus-music-view.c:
(nautilus_music_view_initialize),
(music_view_set_selected_song_title), (reset_playtime),
(play_status_display), (slider_moved_callback),
(add_play_controls):
* components/notes/nautilus-notes.c: (notes_load_metainfo):
* components/services/install/lib/eazel-install-logic.c:
(eazel_install_check_for_file_conflicts),
(eazel_install_do_transaction_all_files_check),
(eazel_install_prune_packages_helper),
(eazel_install_check_existing_packages):
* libnautilus-extensions/nautilus-string.c: (nautilus_strcmp),
(nautilus_strcasecmp), (nautilus_strcmp_case_breaks_ties),
(nautilus_strcoll), (nautilus_str_is_equal),
(nautilus_istr_is_equal), (nautilus_strcmp_compare_func),
(nautilus_strcoll_compare_func),
(nautilus_strcasecmp_compare_func):
* src/file-manager/fm-directory-view.c: (open_location):
* src/nautilus-first-time-druid.c: (make_anti_aliased_label),
(make_hbox_user_level_radio_button), (set_up_user_level_page):
Added bug numbers to FIXMEs. At one point Josh made some bugs for
FIXMEs but never got around to checking in the bug numbers in the
source code. And I wrote one bug report.
* components/music/nautilus-music-view.c:
(nautilus_music_view_initialize): Removed a fixed FIXME. Also got
rid of a hard-coded constant and took excess spaces out of some
string constants.
* components/services/install/lib/eazel-install-object.c:
(eazel_install_emit_dependency_check_default): Changed a FIXME
into a non-FIXME comment, now the the bug is fixed.
* components/services/install/lib/eazel-package-system-rpm3.c:
(rpm_packagedata_fill_from_file): Removed an incorrect bug number
from a FIXME.
* components/services/install/nautilus-view/nautilus-service-install-view.h:
* components/services/install/nautilus-view/nautilus-service-install-view.c:
(nautilus_service_install_installing): Removed the FIXME from a
comment that's about how a bug was fixed.
* components/services/trilobite/libtrilobite/trilobite-md5-tools.h:
* components/services/trilobite/libtrilobite/trilobite-md5-tools.c:
* docs/style-guide.html:
Removed FIXME and corrected misunderstanding about whether use of
the guchar typedef is recommended in Nautilus coding style.
* libnautilus-extensions/nautilus-gdk-font-extensions.h:
* libnautilus-extensions/nautilus-gdk-font-extensions.c:
Removed misguided use of const in here. Gdk and Gtk object types
just aren't suitable for const, and you end up doing type casts
that defeat the purpose.
* src/nautilus-window-manage-views.c: (load_underway_callback):
Remove a FIXME for a fixed bug.
2000-11-13 Mathieu Lacage <mathieu@eazel.com>
Buddy: pavel.
Fix bug 2422 and 4382.
* components/tree/nautilus-tree-view.c:
(filtering_changed_callback),
(collapse_time_callback): added. collapses opened folders when
you leave the tree view.
(nautilus_tree_view_drag_leave): make it call tree_view_drag_destroy
(nautilus_tree_view_drag_motion): cleanup, make it call
tree_view_drag_destroy_real
(nautilus_tree_view_drag_drop): spaces.
(nautilus_tree_view_drag_data_received): cleanup: make it call
tree_view_drag_destroy.
(nautilus_dump_info): cleanup.
(expand_time_callback): cleanup.
(nautilus_tree_view_expand_maybe_later): cleanup
(nautilus_tree_view_collapse_all): cleanup.
(nautilus_tree_view_receive_dropped_icons): make it collapse
correctly.
(nautilus_tree_view_prelight_stop): new function: clears prelighting.
(nautilus_tree_view_drag_destroy): new function: destroys when drag finished.
(nautilus_tree_view_drag_destroy_real): new function: destroys when drag begins.
* docs/dnd.txt: add some thoughts.
* libnautilus-extensions/nautilus-drag.c:
(nautilus_drag_init): init new field.
* libnautilus-extensions/nautilus-drag.h: add shared field to public structure.
2000-10-13 Mathieu Lacage <mathieu@eazel.com>
* docs/state-machines.txt: new design for the state
machine taking into account the new async states.
* libnautilus-extensions/nautilus-bonobo-extensions.c:
(nautilus_bonobo_set_icon), (oaf_activation_callback),
(nautilus_bonobo_activate_from_id),
(nautilus_bonobo_activate_stop),
(nautilus_bonobo_activate_free):
add async activation call.
* libnautilus-extensions/nautilus-bonobo-extensions.h:
add prototypes.
* src/nautilus-view-frame.c:
(nautilus_view_frame_initialize_class), (view_frame_activating),
(view_frame_not_activated), (view_frame_activated),
(view_frame_stop_activation), (view_frame_wait),
(view_frame_underway), (view_frame_wait_is_over),
(view_frame_loaded), (view_frame_failed),
(nautilus_view_frame_set_to_component), (activation_callback),
(nautilus_view_frame_load_client_async),
(nautilus_view_frame_load_client),
(nautilus_view_frame_stop_activation),
(nautilus_view_frame_load_location):
implement new state machine. add comments to explain by which stimulus
the state-chaging functions are triggered.
* src/nautilus-view-frame.h:
add prototype for new async activation function of ViewFrames.
