Imported Upstream version 20090110

[ion3.git] / ioncore / navi.c

diff --git a/ioncore/navi.c b/ioncore/navi.c
index f52a44bf9739ce9b83e36115586317e36680e1cb..7dfd19bb9c682c25f202ba042b82c30848dadf17 100644 (file)
--- a/ioncore/navi.c
+++ b/ioncore/navi.c
@@ -1,12 +1,9 @@
 /*
  * ion/ioncore/navi.c
  *
- * Copyright (c) Tuomo Valkonen 2006. 
+ * Copyright (c) Tuomo Valkonen 2006-2009. 
  *
- * Ion is free software; you can redistribute it and/or modify it under
- * the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation; either version 2.1 of the License, or
- * (at your option) any later version.
+ * See the included file LICENSE for details.
  */
 
 #include <string.h>
@@ -120,6 +117,7 @@ static bool may_ascend(WRegion *to, WRegion *from, WRegionNaviData *data)
     }else if(data->no_ascend!=NULL){
         return (data->no_ascend!=(Obj*)from);
     }else{
+        /* Set to TRUE for cycling out of nested workspaces etc. */
         return !OBJ_IS(from, WMPlex);
     }
 }
@@ -136,6 +134,7 @@ static bool may_descend(WRegion *to, WRegion *from, WRegionNaviData *data)
     }else if(data->no_descend!=NULL){
         return (data->no_descend!=(Obj*)from);
     }else{
+        /* Set to TRUE for cycling into nested workspaces etc. */
         return !OBJ_IS(to, WMPlex);
     }
 }
@@ -228,12 +227,13 @@ static WRegion *release(WRegionNaviData *data, WRegion *res)
 
 /*EXTL_DOC
  * Find region next from \var{reg} in direction \var{dirstr}
- * (up/down/left/right/next/prev/any). The table param may
- * contain the boolean field \var{nowrap}, instructing not to wrap 
+ * (\codestr{up}, \codestr{down}, \codestr{left}, \codestr{right}, 
+ * \codestr{next}, \codestr{prev}, or \codestr{any}). The table \var{param}
+ * may contain the boolean field \var{nowrap}, instructing not to wrap 
  * around, and the \type{WRegion}s \var{no_ascend} and \var{no_descend},
- * and functions \var{ascend_filter} and \var{descend_filter} from
- * \var{WRegion}s (\var{to}, \var{from}), used to decide when to descend
- * or ascend into another region. (TODO: more detailed explanation.)
+ * and boolean functions \var{ascend_filter} and \var{descend_filter} 
+ * on \var{WRegion} pairs (\var{to}, \var{from}), are used to decide when
+ * to descend or ascend into another region.
  */
 EXTL_EXPORT
 WRegion *ioncore_navi_next(WRegion *reg, const char *dirstr, ExtlTab param)
@@ -262,19 +262,16 @@ WRegion *ioncore_navi_next(WRegion *reg, const char *dirstr, ExtlTab param)
 
 
 /*EXTL_DOC
- * Find first region within \var{reg} in direction \var{dirstr}
- * (up/down/left/right/beg/end/any). For information on \var{param},
- * see \fnref{ioncore.navi_next}.
+ * Find first region within \var{reg} in direction \var{dirstr}.
+ * For information on \var{param}, see \fnref{ioncore.navi_next}.
  */
 EXTL_EXPORT
 WRegion *ioncore_navi_first(WRegion *reg, const char *dirstr, ExtlTab param)
 {
     WRegionNaviData data;
     
-    if(reg==NULL){
-        /* ??? */
+    if(reg==NULL)
         return NULL;
-    }
     
     if(!get_param(&data, dirstr, param))
         return NULL;
@@ -288,21 +285,18 @@ WRegion *ioncore_navi_first(WRegion *reg, const char *dirstr, ExtlTab param)
 
 static WRegion *do_goto(WRegion *res)
 {
-    if(res!=NULL){
-        /* TODO: deep rqorder? */
-        region_rqorder(res, REGION_ORDER_FRONT);
+    if(res!=NULL)
         region_goto(res);
-    }
+    
     return res;
 }
 
 
 /*EXTL_DOC
- * Go to region next from \var{reg} in direction \var{dirstr}
- * (up/down/left/right/next/prev/any). For information on \var{param},
- * see \fnref{ioncore.navi_next}. Additionally this function supports
- * the boolean \var{nofront} field, for not bringing the object to
- * front.
+ * Go to region next from \var{reg} in direction \var{dirstr}.
+ * For information on \var{param}, see \fnref{ioncore.navi_next}.
+ * Additionally this function supports the boolean \var{nofront}
+ * field, for not bringing the object to front.
  */
 EXTL_EXPORT
 WRegion *ioncore_goto_next(WRegion *reg, const char *dirstr, ExtlTab param)
@@ -312,11 +306,10 @@ WRegion *ioncore_goto_next(WRegion *reg, const char *dirstr, ExtlTab param)
 
 
 /*EXTL_DOC
- * Go to first region within \var{reg} in direction \var{dirstr}
- * (up/down/left/right/beg/end/any). For information on \var{param},
- * see \fnref{ioncore.navi_next}. Additionally this function supports
- * the boolean \var{nofront} field, for not bringing the object to
- * front.
+ * Go to first region within \var{reg} in direction \var{dirstr}.
+ * For information on \var{param}, see \fnref{ioncore.navi_next}. 
+ * Additionally this function supports the boolean \var{nofront} field,
+ * for not bringing the object to front.
  */
 EXTL_EXPORT
 WRegion *ioncore_goto_first(WRegion *reg, const char *dirstr, ExtlTab param)