Rust-Iup rust: iup-rust — IUP bindings

IUP Rust Build StatusJoin the chat at https://gitter.im/dcampbell24/iup-rust

This library provides a high level wrapper around IUP, a multi-platform toolkit for building graphical user interfaces. See rust-iup-sys for low level bindings.

IUP is a multi-platform toolkit for building graphical user interfaces.

It's purpose is to allow a program to run in different systems without changes - the toolkit provides the application portability. Supported systems include: GTK+, Motif and Windows.

IUP has some advantages over other interface toolkits available:

  • Simplicity: due to the small number of functions and to its attribute mechanism, the learning curve for a new user is often faster.
  • Portability: the same functions are implemented in each one of the platforms, thus assuring the interface system's portability.
  • Customization: the dialog specification language (LED) is a mechanisms in which it is possible to customize an application for a specific user with a simple-syntax text file.
  • Flexibility: its abstract layout mechanism provides flexibility to dialog creation.
  • Extensibility: the programmer can create new interface elements as needed.

The Rust binding provides a way to do things in a more Rustic way but without moving out of IUP base nameclatures and philosophy in such a way that one can program on this binding by reading the original IUP documentation.

Documentation

Click the link above or run cargo doc on this repository to view the documentation locally.

Installation

See rust-iup-sys for information on installing the IUP system libraries needed to use this library. After you have the IUP system libraries just add this to your Cargo.toml:

[dependencies.iup]
git = "https://github.com/dcampbell24/iup-rust"

Contribute

Contributions are welcome both in the form of ideas and of code. If you want to work on something, please open a issue to let others know what you are working on. If you are not sure what to work on, check our issues to see what must be worked on.

If you find any issues with the library, please create a GitHub issue for it.

Comments

  • Resources
    Resources

    May 27, 2015

    Tracking progress on resources. If you wish to implement any of those items leave a comment :)

    • [x] LED
    • [ ] Fonts
      • Since fonts are attributes (working) and the purpose of this item is to have a trait for fonteable controls, it's not a priority right now.
    • [x] Images
    • [ ] Keyboard
    • [ ] Menus
    • [ ] Handle Names
      • [x] IupSetHandle
      • [x] IupGetHandle
      • [x] IupGetName
      • [ ] IupGetAllNames
      • [ ] IupGetAllDialogs
    • [ ] String Names
      • [ ] IupSetLanguage
      • [ ] IupGetLanguage
      • [ ] IupSetLanguageString
      • [ ] IupGetLanguageString
      • [ ] IupSetLanguagePack
    • [x] IupClipboard
    • [x] IupTimer
    • [ ] IupUser
    • [ ] IupConfig
    • [ ] IupHelp
    help wanted 
    Reply
  • Attributes
    Attributes

    May 28, 2015

    Tracking progress on attributes. If you wish to implement any of those items leave a comment :)

    This issue is not about method to access individual attributes on each control, instead about the general attribute system. At this moment making attributes as methods is not a priority (but will mostly like come to life later on) and thus why this is not a track of attribute as methods.

    Main: Some of the items here must be skeptically taken a look to realize if they are actually needed.

    • [ ] IupSetAttribute
      • [x] IupSetAttribute
      • [x] IupSetStrAttribute
      • [ ] IupSetAttributeId
      • [ ] IupSetStrAttributeId
      • [ ] IupSetAttributeId2
      • [ ] IupSetStrAttributeId2
    • [x] IupResetAttribute
    • [x] IupSetAttributeHandle
    • [ ] IupGetAttribute
      • [x] IupGetAttribute
      • [x] IupGetStrAttribute
      • [ ] IupGetAttributeId
      • [ ] IupGetStrAttributeId
      • [ ] IupGetAttributeId2
      • [ ] IupGetStrAttributeId2
    • [x] IupGetAllAttributes
    • [x] IupGetAttributeHandle
    • [x] IupSetGlobal
    • [x] IupSetStrGlobal
    • [x] IupGetGlobal
    • [x] IupGetStrGlobal

    The IupSetAttributes IupGetAttributes, and IupSetAtt aren't going to be implemented either because they don't fit rust or to avoid over-bloat of functions that does essentially the same thing with no advantage over the simpler version.

    Sub functions will not to be implemented (at least not until we start doing attribute methods), they are a major bloat that does not even provide a performance gain (please leave a comment if you disagree with this!)

    help wanted 
    Reply
  • Events
    Events

    May 28, 2015

    Tracking progress on the events section of iup docs. If you wish to implement any of those items leave a comment :)

    Functions:

    • [x] IupMainLoop
      • Wrapped in with_iup.
    • [ ] IupMainLoopLevel
      • Must make with_iup be able to be called several times like IupMainLoop is able to.
    • [ ] IupLoopStep
    • [ ] IupExitLoop
    • [ ] IupFlush
    • [ ] IupGetCallback
    • [X] IupSetCallback
      • Abstracted off in the callback submodule.
    • [ ] IupRecordInput
    • [ ] IupPlayInput

    IupSetCallbacks won't be implemented.

    Common:

    • [x] IDLE_ACTION
    • [x] MAP_CB
    • [x] UNMAP_CB
    • [x] DESTROY_CB
    • [x] GETFOCUS_CB
    • [x] KILLFOCUS_CB
    • [x] ENTERWINDOW_CB
    • [x] LEAVEWINDOW_CB
    • [ ] K_
      • [ ] K_ANY
      • [ ] K_*
    • [x] HELP_CB
    • [x] ACTION

    Other:

    • [ ] Drag&Drop
    help wanted 
    Reply
  • Function Conventions
    Function Conventions

    May 28, 2015

    Some conventions on the functions must be discussed...

    Null parameters

    Some functions allow null pointers to be passed to them.. For instance IupInsert and IupReparent allow the ref_child parameter to be NULL essentially making the first found child to be used as the ref_child.

    Currently our binding enforces the passing of ref_child (i.e. it's not a Option).

    fn insert<E1, E2>(&mut self, ref_child: &E1, new_child: E2) -> Result<Handle, E2>
                    where E1: Element, E2: Element {
    

    The thing is, if it was a Option, passing None as parameter would bring a error that it does not know enough about E1 constraint and thus we'd need to specify it explicitly (e.g. None::<Handle>) and that does not look quite beauty.

    What should be done in such cases?

    There is also this other related on Dialogs:

    pub fn new<E: Element>(child: E) -> Dialog
    pub fn new_empty() -> Dialog
    

    Didn't use a single new with a Option parameter for that very same reason.

    And that brings us to another issue.

    Constructor namings

    Should we use a fn new<E: Element>(child: E) -> Dialog or fn with<E: Element>(child: E) -> Dialog or use a Option (see previous topic)? The same question applies to layout boxes and other container objects.

    If still new without Option should the empty version be named new_empty?

    As a side note, buttons (and other future controls?!) does it this way:

    fn new() -> Button
    fn with_title<S: Into<String>>(title: S) -> Button
    fn with_image(image: ?)  -> Button // in the future
    

    Get/Set

    Currently the library follows Rust guidelines of setters having a set_ prefix and getters having no prefix (e.g. set_attrib sets and attrib gets, parent instead of get_parent and so on), that seems the way to go but if there's any contradiction to it please enlighten me.

    Result

    Since IUP does not give any manner of a descriptive error message (with strings), we shouldn't perhaps be returning Result<T, String> mainly in the cases only IUP_NOERROR and IUP_ERROR are possible.

    We should be using Result<T, ()> (or anything along those lines) for the case where there can be only one single error (e.g. IUP_ERROR) and use a Result<T, Enum in cases it may return different error types (i.e. with_iup).

    Another issue with strings is that they cannot be matched to easily find out what happened wrong in the multi-error case.

    Reply
  • Use UTF-8 mode
    Use UTF-8 mode

    May 29, 2015

    IUP uses a encoding depending on the C locale, Rust is Unicode aware by the means of UTF-8. Thus the UTF-8 mode of IUP must be enabled by us right after calling IupOpen, the global attributes are UTF8MODE and UTF8MODE_FILE (docs here).

    Additionally it should be clearly documented we turn UTF-8 mode ON so the user don't need to worry about it.

    Reply
  • Timer Guard is much too easy to mis-use
    Timer Guard is much too easy to mis-use

    Oct 29, 2015

    I suggest removing the Self return type from run, stop and set_time. Or changing it to &mut Self so chaining still works but you don't accidentally unwrap the Guard while still having the guard.

    Even better would probably be to remove the Guard alltogether and implement Drop for Timer. That would remove the possibility for others to stop/start the timer. So another way would be to simply use Rc instead of Guard.

    Reply
  • The Object Model
    The Object Model

    May 17, 2015

    A step to the a high-level binding is to decide the object model to be used, each has pros and cons, mainly because of the C model used in IUP.

    Note: The pros and cons lists are not exhaustive, please consider adding more if any comes to mind.

    Terminology:

    • string attributes: Using IupGetAttribute and IupSetAttribute which gets and sets a string instead of a well specified object type.
    • function/methods for attributes: Using a function/method for each attribute, giving more type safety to it since each of those functions will set/get the correct type of the attribute instead of a string.

    Ihandle and Functions (using string attributes)

    This is the current model in the library, all the IUP objects are described with a Ihandle structure and passed to functions as the first argument.

    Pros:

    • Simple model.
    • Maps 1:1 to IUP documentation

    Cons:

    • Attributes aren't type-safe.
    • Not possible to find out about attributes by using auto-completion.
    • Annoying &mut handle on each function call.

    Ihandle and Functions (using functions for attributes)

    Pros

    • Simple model.
    • Maps almost 1:1 to IUP documentation.
    • Type-safe attributes.
    • Possible to find out about attributes by using auto-completion.

    Cons:

    • Annoying &mut handle on each function call.

    Ihandle and Methods

    Mirror Ihandle and Functions (using string attributes) and Ihandle and Functions (using functions for attributes) here by excluding the Annoying &mut handle on each function call cons.

    Structs/Traits and Methods (using methods for attributes)

    Pros:

    • More Rusty
    • Very type-safe.
    • Possible to find out about attributes by using auto-completion + only the attributes and callbacks that applies to this object in question.

    Cons:

    • Complex model.
    • Does not map 1:1 to IUP documentation.

    Issues:

    • How to deal with functions that returns a handle to any kind of object (e.g. IupGetHandle)?
    Reply
  • IupConvertXYToPos in it's own trait or object
    IupConvertXYToPos in it's own trait or object

    May 28, 2015

    IupConvertXYToPos is limited to a few elements (IupText, IupScintilla, IupList, IupTree and IupMatrix), it's currently implemented in the Element trait.

    However it seems like a case it should be either:

    • Move into a separate trait...
    • or maybe add directly in the implementation of those specific controls.

    Thoughts?

    Reply
  • Hierarchy Operations in a separate trait
    Hierarchy Operations in a separate trait

    May 28, 2015

    There are two types of elements:

    • Those that are containers (e.g. dialog, frame, hbo, vbox, etc) and can store other elements in it. They can have parents, childs and a brother. For instance IupAppend only works on those containers.
    • Those that are final nodes, they can have parents and a brother but cannot have childs. The container containers are a superset of this node type.

    Currently all the hierarchy operations are implemented in the Element trait. Should those prehaps be separated in two traits instead of leaving them in Element?

    The upside I see is that it'll be cleaner which objects are containers and which aren't. The downsides is that Handle would need to implement both (?) and give the doubt if the contained handle is really part of that trait.

    Reply
  • Rusty Callbacks
    Rusty Callbacks

    May 16, 2015

    Adds the ability to use Rust closures as callbacks to IUP. Very trivial to add new callbacks, see the impl_callback! documentation.

    Also see examples/counter_newcb.rs for examples/counter.rs rewritten with closures.

    Reply
  • High-level Overhaul
    High-level Overhaul

    May 27, 2015

    Closes #6. Opening this pull instead of merging straight away to master to discuss if it's all good.

    Reply
  • Few changes
    Few changes

    May 24, 2015

    Changes:

    • iup::open returns a RAII object.
    • Use slices instead of Vec arguments.
    • Added IupLoad and IupLoadBuffer.
    Reply