libgnt/libgnt

Add a migration guide, based on GTK's.

2019-05-20, Elliott Sales de Andrade
d27f187aca34
Parents 8ebf70041b89
Children 04d9c8e5cb95
Add a migration guide, based on GTK's.

This replaces ChangeLog.API. Much of the boilerplate text is from GTK,
though it's been modified to only contain information applicable to
this project.
4 files changed, 137 insertions(+), 271 deletions(-)
  • +0 -271
    ChangeLog.API
  • +14 -0
    doc/libgnt-docs.xml
  • +6 -0
    doc/meson.build
  • +117 -0
    doc/migrating-2to3.xml
    • --- a/ChangeLog.API Mon May 20 21:57:43 2019 -0400
    +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
    @@ -1,271 +0,0 @@
    -GNT: The GLib Ncurses Toolkit
    -=============================
    -
    -Please see notes about versioning in README.md.
    -
    -This file intends to list all changes to libgnt's public API. We sometimes
    -forget to add changes to this file--sorry.
    -
    -If your plugin fails to build with a new major version (e.g. 3.0.0) we suggest
    -checking this list first, in case a function was simply renamed.
    -You may still need to consult our API docs or our source code.
    -
    -If you notice something missing from this list, please let us know and we'll
    -add it.
    -
    -version 3.0.0 (????/??/??):
    - Changed:
    - * ENTRY_CHAR renamed to GNT_ENTRY_CHAR
    - * g_hash_table_duplicate renamed to gnt_hash_table_duplicate
    - * GDupFunc renamed to GntDuplicateFunc
    -
    - Removed:
    - * _GntFileType
    - * _GntKeyPressMode
    - * _GntMouseEvent
    - * _GntParamFlags
    - * _GntProgressBarOrientation
    - * _GntTreeColumnFlag
    - * _GntWidgetFlags
    - * gnt_boolean_handled_accumulator; use
    - g_signal_accumulator_true_handled instead.
    - * gnt_widget_bindings_view; use gnt_bindable_bindings_view instead.
    -
    -version 2.13.0 (2018/03/08):
    - No changes.
    -
    -version 2.12.0 (2017/03/09):
    - No changes.
    -
    -version 2.11.0 (2016/06/21):
    - No changes.
    -
    -version 2.10.12 (2015/12/31):
    - No changes.
    -
    -version 2.10.11 (2014/11/23):
    - No changes.
    -
    -version 2.10.10 (2014/10/22):
    - No changes.
    -
    -version 2.10.9 (2014/02/02):
    - No changes.
    -
    -version 2.10.8 (2014/01/28):
    - No changes.
    -
    -version 2.10.7 (2013/02/13):
    - No changes.
    -
    -version 2.10.6 (2012/07/06):
    - No changes.
    -
    -version 2.10.5 (2012/07/05):
    - No changes.
    -
    -version 2.10.4 (2012/05/06):
    - No changes.
    -
    -version 2.10.3 (2012/03/26):
    - No changes.
    -
    -version 2.10.2 (2012/03/14):
    - No changes.
    -
    -version 2.10.1 (2011/12/06):
    - No changes.
    -
    -version 2.10.0 (2011/08/18):
    - No changes.
    -
    -version 2.9.0 (2011/06/23):
    - No changes.
    -
    -version 2.8.0 (2011/06/07):
    - No changes.
    -
    -version 2.7.11 (2011/03/10):
    - No changes.
    -
    -version 2.7.10 (2011/02/06):
    - No changes.
    -
    -version 2.7.9 (2010/12/26):
    - No changes.
    -
    -version 2.7.8 (2010/12/19):
    - No changes.
    -
    -version 2.7.7 (2010/11/23):
    - No changes.
    -
    -version 2.7.6 (2010/11/21):
    - No changes.
    -
    -version 2.7.5 (2010/10/31):
    - No changes.
    -
    -version 2.7.4 (2010/10/20):
    - No changes.
    -
    -version 2.7.3 (2010/08/10):
    - Added:
    - * gnt_tree_row_get_child
    - * gnt_tree_row_get_key
    - * gnt_tree_row_get_next
    - * gnt_tree_row_get_parent
    - * gnt_tree_row_get_prev
    -
    -version 2.7.2 (2010/07/21):
    - No changes.
    -
    -version 2.7.1 (2010/05/29):
    - No changes.
    -
    -version 2.7.0 (2010/05/12):
    - Added:
    - * GntEntrySearch *search; member to GntEntry
    -
    -version 2.6.6 (2010/02/18):
    - No changes.
    -
    -version 2.6.5 (2010/01/08):
    - No changes.
    -
    -version 2.6.4 (2009/11/29):
    - No changes.
    -
    -version 2.6.3 (2009/10/16):
    - No changes.
    -
    -version 2.6.2 (2009/09/05):
    - No changes.
    -
    -version 2.6.1 (2009/08/18):
    - No changes.
    -
    -version 2.6.0 (2009/08/18):
    - Added:
    - * GntProgressBar and functions (Saleem Abdulrasool)
    -
    -version 2.5.9 (2009/08/18):
    - No changes.
    -
    -version 2.5.8 (2009/06/27):
    - No changes.
    -
    -version 2.5.7 (2009/06/20):
    - No changes.
    -
    -version 2.5.6 (2009/05/19):
    - No changes.
    -
    -version 2.5.5 (2009/03/01):
    - No changes.
    -
    -version 2.5.4 (2009/01/12):
    - No changes.
    -
    -version 2.5.3 (2008/12/20):
    - No changes.
    -
    -version 2.5.2 (2008/10/19):
    - No changes.
    -
    -version 2.5.1 (2008/08/30):
    - No changes.
    -
    -version 2.5.0 (2008/08/18):
    - No changes.
    -
    -version 2.4.2 (2008/05/17):
    - Added:
    - * gnt_bindable_check_key to check if a keystroke is bound.
    -
    -version 2.4.1 (2008/03/31):
    - No changes.
    -
    -version 2.4.0 (2008/02/29):
    - Added:
    - * gnt_tree_set_row_color to set the color for a row in a tree.
    - * gnt_style_get_string_list
    - * gnt_color_add_pair to define a new color.
    - * gnt_colors_get_color to get an ncurses color value from a string.
    - * gnt_style_get_color to get a color pair from an entry in ~/.gntrc
    - * gnt_tree_get_parent_key to get the key for the parent row.
    -
    -version 2.3.0 (2007/11/24):
    - Added:
    - * gnt_color_pair, which will try to intelligenty set text attributes
    - in place of colors if the terminal doesn't have color support. (Bug:
    - #3560) All future code should use gnt_color_pair instead of
    - COLOR_PAIR.
    - * gnt_menuitem_set_id and gnt_menuitem_get_id to set and get the
    - string id of a menuitem respectively.
    - * gnt_window_get_accel_item, which returns a the id of a menuitem
    - bound to a keystroke.
    - * gnt_menu_get_item to get a menuitem of the given id from a menu.
    - * gnt_menuitem_activate, which triggers the 'activate' signal on the
    - menuitem and calls the callback function, if available.
    - * GntEntryKillRing in GntEntry.
    - * gnt_window_set_maximize and gnt_window_get_maximize, and
    - GntWindowFlags enum.
    -
    -version 2.2.2 (2007/10/23):
    - No changes.
    -
    -version 2.2.1 (2007/09/29):
    - No changes.
    -
    -version 2.2.0 (2007/09/13):
    - Added:
    - * gnt_slider_set_small_step, gnt_slider_set_large_step to allow more
    - fine tuned updates of a GntSlider
    - * gnt_util_parse_xhtml_to_textview to parse XHTML strings in a
    - GntTextView (this works only if libxml2 is available)
    -
    -version 2.1.1 (2007/08/20):
    - Added:
    - * gnt_bindable_bindings_view
    - * gnt_bindable_build_help_window
    - * GNT_TEXT_VIEW_TOP_ALIGN
    -
    -version 2.1.0 (2007/07/28):
    - Added:
    - * GntWS for workspaces
    - * gnt_tree_set_column_title
    - * GntSlider widget
    - * "completion" signal for GntEntry
    - * "terminal-refresh" signal for GntWM, with a corresponding entry in
    - GntWMClass
    - * New flags for GntTextView to decide whether to word-wrap or show
    - scrollbars (GntTextViewFlag) which can be set by
    - gnt_text_view_set_flag
    - * gnt_style_get_from_name
    - * gnt_window_present
    - * gnt_tree_set_column_width_ratio
    - * gnt_tree_set_column_resizable
    - * gnt_tree_set_column_is_right_aligned
    - * gnt_tree_set_search_function
    - * gnt_tree_set_search_column
    - * gnt_tree_is_searching
    - * 'file-selected' signal is emitted for GntFileSel
    - * gnt_style_parse_bool
    - * gnt_util_set_trigger_widget
    -
    - Changed:
    - * gnt_tree_get_rows() now returns a GList* instead of a const GList*,
    - as const is not very useful with GLists. The returned value still
    - must not be modified or freed.
    - * Instead of keeping an 'invisible' item, the GntTreeColumns now
    - maintain 'flags' with the appropriate flags set
    -
    -version 2.0.2 (2007/06/14):
    - No changes.
    -
    -version 2.0.1 (2007/05/24):
    - No changes.
    -
    -version 2.0.0 (2007/05/03):
    - Initial release.
    --- a/doc/libgnt-docs.xml Mon May 20 21:57:43 2019 -0400
    +++ b/doc/libgnt-docs.xml Mon May 20 22:22:54 2019 -0400
    @@ -89,6 +89,20 @@
    </chapter>
    </part>
    + <!-- Migration guides -->
    + <part id="migrating">
    + <title>Migrating from Previous Versions of GNT</title>
    +
    + <partintro>
    + <para>
    + This part describes what you need to change in programs using older
    + versions of GNT so that they can use the new features.
    + </para>
    + </partintro>
    +
    + <xi:include href="migrating-2to3.xml" />
    + </part>
    +
    <part>
    <title>Appendices</title>
    <index id="api-index-full">
    --- a/doc/meson.build Mon May 20 21:57:43 2019 -0400
    +++ b/doc/meson.build Mon May 20 22:22:54 2019 -0400
    @@ -1,5 +1,10 @@
    DOC_MODULE = 'libgnt'
    +# Extra content files, other than the main one.
    +content_files = [
    + 'migrating-2to3.xml',
    +]
    +
    # Header files or dirs to ignore when scanning. Use base file/dir names
    ignore_headers = [
    'test',
    @@ -31,6 +36,7 @@
    gnome.gtkdoc(DOC_MODULE,
    main_xml : DOC_MODULE + '-docs.xml',
    + content_files : content_files,
    src_dir : libgnt_inc,
    dependencies : libgnt_dep,
    install : true,
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/doc/migrating-2to3.xml Mon May 20 22:22:54 2019 -0400
    @@ -0,0 +1,117 @@
    +<?xml version="1.0"?>
    +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
    +<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
    +]>
    +<chapter id="migrating-2-to-3">
    + <title>Migrating from GNT 2.x to 3</title>
    +
    + <para>
    + GNT 3 is a major new version of GNT that breaks both API and ABI compared
    + to GNT 2.x. There are a number of steps that you can take to prepare your
    + GNT 2.x application for the switch to GNT 3. After that, there's a small
    + number of adjustments that you may have to do when you actually switch your
    + application to build against GNT 3.
    + </para>
    +
    + <section>
    + <title>Preparation in GNT 2.x</title>
    +
    + <para>
    + The steps outlined in the following sections assume that your application
    + is working with GNT 2.14, which is the final stable release of GNT 2.x.
    + It includes all the necessary APIs and tools to help you port your
    + application to GNT 3. If you are still using an older version of GNT 2.x,
    + you should first get your application to build and work with the latest
    + minor release in the 2.14 series.
    + </para>
    +
    + <section>
    + <title>Do not use deprecated symbols</title>
    + <para>
    + Over the years, a number of functions have been deprecated. These
    + deprecations are clearly spelled out in the API reference, with hints
    + about the recommended replacements. The API reference for GNT 2 also
    + includes an <ulink
    + url="https://docs.pidgin.im/libgnt/next/api-deprecated.html">index of
    + all deprecated symbols</ulink>.
    + </para>
    + <para>
    + To verify that your program does not use any deprecated symbols, you
    + can use preprocessor defines to remove deprecated symbols from the
    + header files. As part of your compilation process, you may define the
    + following:
    + <itemizedlist>
    + <listitem>
    + <code>GNT_DISABLE_DEPRECATED</code> to hide deprecated symbols.
    + </listitem>
    + <listitem>
    + <code>GNTSEAL_ENABLE</code> to hide internal struct members.
    + </listitem>
    + </itemizedlist>
    + </para>
    + <para>
    + Note that some parts of our API, such as enumeration values, are not
    + well covered by the deprecation warnings. In most cases, using them
    + will require you to also use deprecated functions, which will trigger
    + warnings.
    + </para>
    + </section>
    + </section>
    +
    + <section>
    + <title>Changes that need to be done at the time of the switch</title>
    +
    + <para>
    + This section outlines porting tasks that you need to tackle when you get
    + to the point that you actually build your application against GNT 3.
    + Making it possible to prepare for these in GNT 2 would have been either
    + impossible or impractical.
    + </para>
    +
    + <section>
    + <title>Removed internal API</title>
    +
    + <para>
    + The following tag names have been removed from the API entirely; use
    + the name without the underscore instead:
    + <itemizedlist>
    + <listitem><code>enum _GntFileType</code></listitem>
    + <listitem><code>enum _GntMouseEvent</code></listitem>
    + <listitem><code>enum _GntParamFlags</code></listitem>
    + <listitem><code>enum _GntProgressBarOrientation</code></listitem>
    + <listitem><code>enum _GntTreeColumnFlag</code></listitem>
    + </itemizedlist>
    +
    + The following items were removed entirely:
    + <itemizedlist>
    + <listitem>
    + <code>enum _GntKeyPressMode</code> and <code>GntKeyPressMode</code>
    + </listitem>
    + <listitem>
    + <code>enum _GntWidgetFlags</code> and <code>GntWidgetFlags</code>
    + </listitem>
    + </itemizedlist>
    + </para>
    + </section>
    +
    + <section>
    + <title>Changed API</title>
    + <para>
    + The following items have been changed as part of the API break:
    + <itemizedlist>
    + <listitem>
    + <code>ENTRY_CHAR</code> renamed to %GNT_ENTRY_CHAR
    + </listitem>
    + <listitem>
    + <code>g_hash_table_duplicate</code> renamed to
    + gnt_hash_table_duplicate()
    + </listitem>
    + <listitem>
    + <code>GDupFunc</code> renamed to #GntDuplicateFunc
    + </listitem>
    + </itemizedlist>
    + </para>
    + </section>
    + </section>
    +</chapter>