Merge pull request #56 from SciTools-incubator/label_animator_buttons

Label animator step functionality

ImageMetaTag/db.py

@@ -65,11 +65,11 @@ def read_img_info_from_dbfile(db_file, required_tags=None, tag_strings=None,
     '''
     reads in the database written by write_img_to_dbfile
 
-    options:
+    Options:
      * required_tags - a list of image tags to return, and to fail if not all are present
      * tag_strings - an input list that will be populated with the unique values of the image tags.
 
-    returns:
+    Returns:
      * a list of filenames (payloads for the :class:`ImageMetaTag.ImageDict` class )
      * a dictionary, by filename, containing a dictionary of the image metadata as *tagname: value*
 
@@ -122,8 +122,8 @@ def merge_db_files(main_db_file, add_db_file, delete_add_db=False, delete_added_
     The databases should have the same tags within them for the merge to work.
 
     Options:
-    * delete_add_db - if True, the added database file will be deleted afterwards
-    * delete_added_entries - if delete_add_db is False, this will keep the add_db_file
+     * delete_add_db - if True, the added database file will be deleted afterwards
+     * delete_added_entries - if delete_add_db is False, this will keep the add_db_file
                              but remove the entries from it which were added to the main_db_file.
                              This is useful if parallel processes are writing to the databases.
                              It does nothing if delete_add_db is True.
@@ -171,11 +171,11 @@ def open_or_create_db_file(db_file, img_info, restart_db=False, timeout=DEFAULT_
     Opens a database file and sets up initial tables, then returns the connection and cursor.
 
     Arguments:
-    * db_file - the database file to open.
-    * img_info - a dictionary of image metadata to be saved to the database.
+     * db_file - the database file to open.
+     * img_info - a dictionary of image metadata to be saved to the database.
 
     Options:
-    * restart_db - when Truem this deletes the current db file and starts again, \
+     * restart_db - when Truem this deletes the current db file and starts again, \
                    if it already exists.
 
     Returns an open database connection (dbcn) and cursor (dbcr)
@@ -303,11 +303,12 @@ def process_select_star_from(db_contents, dbcr, required_tags=None, tag_strings=
     Converts the output from a select * from ....  command into a standard output format
     Requires a database cursor (dbcr) to identify the field names.
 
-    Options
+    Options:
      * required_tags - a list of image tags to return, and to fail if not all are present
      * tag_strings - an input list that will be populated with the unique values of the image tags
 
-    returns as :func:`ImageMetaTag.db.read_img_info_from_dbfile`, but filtered accord to the select.
+    Returns:
+    as :func:`ImageMetaTag.db.read_img_info_from_dbfile`, but filtered accord to the select.
      * a list of filenames (payloads for the :class:`ImageMetaTag.ImageDict`)
      * a dictionary, by filename, containing a dictionary of the image metadata as *tagname: value*
     '''
@@ -578,26 +579,27 @@ def scan_dir_for_db(basedir, db_file, img_tag_req=None, subdir_excl_list=None, k
     the database by accident).
 
     Arguments:
-    * basedir - the directory to start scanning.
-    * db_file - the database file to save the image metadata to. A pre-existing database file\
+     * basedir - the directory to start scanning.
+     * db_file - the database file to save the image metadata to. A pre-existing database file\
                 will fail unless restart_db is True
 
-    * img_tag_req - a list of tag names that are to be applied/created. Tags not in this list\
-                    will not be stored. Images without all of these tags are ignored.
-    * subdir_excl_list - a list of subdirectories that don't need to be scanned. ['thumbnail']\
-                        for instance, will prevent the image thumbnails being included.
-    * no_file_ext - logical to exclude the file extension in the filenames saved to the database.
-    * known_file_tags - if supplied, this is a dict (keyed by filename entry),\
-                        contains a dictionary of {filename: {tag name: value}} already known\
-                        (so you don't need to read them from the files themselves). This is very\
-                        if you have a old backup of a database file that needs updating.
-    * restart_db - if True, the db_file will be restarted as empty.
-    * verbose - verbose output.
+    Options:
+     * img_tag_req - a list of tag names that are to be applied/created. Tags not in this list\
+                     will not be stored. Images without all of these tags are ignored.
+     * subdir_excl_list - a list of subdirectories that don't need to be scanned. ['thumbnail']\
+                         for instance, will prevent the image thumbnails being included.
+     * no_file_ext - logical to exclude the file extension in the filenames saved to the database.
+     * known_file_tags - if supplied, this is a dict (keyed by filename entry),\
+                         contains a dictionary of {filename: {tag name: value}} already known\
+                         (so you don't need to read them from the files themselves). This is very\
+                         if you have a old backup of a database file that needs updating.
+     * restart_db - if True, the db_file will be restarted from an empty database.
+     * verbose - verbose output.
     '''
 
     if os.path.isfile(db_file) and not restart_db:
         raise ValueError('''scan_dir_for_db will not work on a pre-existing file unless restart_db
-is True, in which case the database file will be restarted. Use with care.''')
+is True, in which case the database file will be restarted as empty. Use with care.''')
 
     if known_file_tags is not None:
         known_files = known_file_tags.keys()

ImageMetaTag/webpage.py

@@ -64,7 +64,7 @@ def write_full_page(img_dict, filepath, title, page_filename=None, tab_s_name=No
     * postable : html text added after the ImageMetaTag section.
     * initial_selectors - A list of initial values for the selectors, to be passed into \
                           :func:`ImageMetaTag.webpage.write_js_setup`.
-    * show_selector_names - switches on diplsaying the selector full names defined by the \
+    * show_selector_names - switches on displaying the selector full names defined by the \
                             :class:`ImageMetaTag.ImageDict`.full_name_mapping
     * url_type - determines the type of URL at the bottom of the ImageMetaTag section. Can be \
                  'int' or 'str'.
@@ -243,8 +243,14 @@ def write_full_page(img_dict, filepath, title, page_filename=None, tab_s_name=No
                 level_names = img_dict.level_names
             else:
                 level_names = False
+            # if we're labelling selectors, and we have an animator button, label that too:
+            if img_dict.selector_animated > 1 and show_selector_names:
+                anim_level = level_names[img_dict.selector_animated]
+            else:
+                anim_level = None
             write_js_placeholders(file_obj=out_file, dict_depth=img_dict.dict_depth(),
-                                  style=style, level_names=level_names)
+                                  style=style, level_names=level_names,
+                                  animated_level=anim_level)
         # the body is done, so the postamble comes in:
         if not postamble is None:
             out_file.write(postamble + '\n')
@@ -454,7 +460,8 @@ def write_json(img_dict, json_file):
         json_file.write(out_str)
 
 def write_js_placeholders(file_obj=None, dict_depth=None, selector_prefix=None,
-                          style='horiz dropdowns', level_names=False):
+                          style='horiz dropdowns', level_names=False,
+                          animated_level=None):
     '''
     Writes the placeholders into the page body, for the javascript to manipulate
 
@@ -466,6 +473,7 @@ def write_js_placeholders(file_obj=None, dict_depth=None, selector_prefix=None,
               they are always horizontal dropdown menus: 'horiz dropdowns'.
     * level_names - if supplied, this need to be a list of full names, for the selectors, of \
                     length dict_depth.
+    * animated_level - if supplied, as a string, this will be used to label the animator buttons.
     '''
 
     if selector_prefix is None:
@@ -488,6 +496,12 @@ def write_js_placeholders(file_obj=None, dict_depth=None, selector_prefix=None,
  <tr>
   <td>
    <font size=3>''')
+        # a text label for the animator buttons:
+        if isinstance(animated_level, str):
+            anim_label = '{}: '.format(animated_level)
+        else:
+            anim_label = ''
+
         # for each level of depth in the plot dictionary, add a span to hold the selector:
         if apply_level_names:
             # if we want labelled selectors, then write out
@@ -510,12 +524,12 @@ def write_js_placeholders(file_obj=None, dict_depth=None, selector_prefix=None,
             # add the placeholder for animators buttons:
             file_obj.write('''     <tr>
       <td colspan={}>
-        <span id="animator1">&nbsp;</span>
+        {}<span id="animator1">&nbsp;</span>
         <span id="animator2">&nbsp;</span>
       </td>
     </tr>
    </table>
-'''.format(dict_depth))
+'''.format(dict_depth, anim_label))
         else:
             # simply a set of spans, in a line:
             for lev in range(dict_depth):
@@ -524,10 +538,10 @@ def write_js_placeholders(file_obj=None, dict_depth=None, selector_prefix=None,
             file_obj.write('\n   <br>')
             # add the placeholder for animators buttons:
             file_obj.write('''
-   <span id="animator1">&nbsp;</span>
+   {}<span id="animator1">&nbsp;</span>
    <span id="animator2">&nbsp;</span>
        <br>
-    ''')
+    '''.format(anim_label))
 
         # now add somewhere for the image to go:
         file_obj.write('''   <div id="the_image">Please wait while the page is loading</div>

docs/build/html/ImageDict.html

@@ -95,7 +95,7 @@ <h3>Quick search</h3>
   <div class="section" id="module-ImageMetaTag.img_dict">
 <span id="imagemetatag-imagedict"></span><h1>ImageMetaTag.ImageDict<a class="headerlink" href="#module-ImageMetaTag.img_dict" title="Permalink to this headline">¶</a></h1>
 <p>This submodule contains the <a class="reference internal" href="#ImageMetaTag.ImageDict" title="ImageMetaTag.ImageDict"><tt class="xref py py-class docutils literal"><span class="pre">ImageMetaTag.ImageDict</span></tt></a> class, and functions for preparing them.</p>
-<p>The purpose of an <a class="reference internal" href="#ImageMetaTag.ImageDict" title="ImageMetaTag.ImageDict"><tt class="xref py py-class docutils literal"><span class="pre">ImageMetaTag.ImageDict</span></tt></a> is to sort the image metadata, supplied to 
+<p>The purpose of an <a class="reference internal" href="#ImageMetaTag.ImageDict" title="ImageMetaTag.ImageDict"><tt class="xref py py-class docutils literal"><span class="pre">ImageMetaTag.ImageDict</span></tt></a> is to sort the image metadata, supplied to
 <a class="reference internal" href="savefig.html#ImageMetaTag.savefig" title="ImageMetaTag.savefig"><tt class="xref py py-func docutils literal"><span class="pre">ImageMetaTag.savefig()</span></tt></a> and usually stored in a database file, into a useful form that
 can quickly and easily be presented as a webpage by <a class="reference internal" href="webpage.html#ImageMetaTag.webpage.write_full_page" title="ImageMetaTag.webpage.write_full_page"><tt class="xref py py-func docutils literal"><span class="pre">ImageMetaTag.webpage.write_full_page()</span></tt></a>.</p>
 <p>An easy example of creating a webpage, using an ImageDict is shown in