dmaax/ladybird
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ladybird/Documentation/Browser/AddNewIDLFile.md

43 lines
2.1 KiB
Markdown
Raw Normal View History

Documentation: Add documentation for adding IDL files There are several steps involved, which are not at all obvious unless you already know them. So now they're written down. :^)
2021-10-03 17:32:01 -03:00
# Adding a new IDL file
Serenity's build system does a lot of work of turning the IDL from a Web spec into code, but there are a few things you'll need to do yourself.
For the sake of example, let's say you're wanting to add the `HTMLDetailsElement`.
1. Create `LibWeb/HTML/HTMLDetailsElement.idl` with the contents of the IDL section of the spec. In this case, that would be:
```webidl
[Exposed=Window]
interface HTMLDetailsElement : HTMLElement {
[HTMLConstructor] constructor();
[CEReactions] attribute boolean open;
};
```
Documentation: Correct and update IDL documentation - Delete the part about removing `[Exposed=Window]` since that's not necessary and we may want that information there to generate the Window object. - Mention adding `#import`s. - Outline the requirements for the implementation class. - Mention the non-Event wrapper factories that need to know about certain types. I tend to refer to this document every time I add an IDL type so it's helpful if it's comprehensive.
2022-04-22 16:18:16 -03:00
2. If the IDL refers to other IDL types, you need to import those. For example, `CSSRule` has an attribute that returns a `CSSStyleSheet`, so that needs to be imported:
```webidl
#import <CSS/CSSStyleSheet.idl>
interface CSSRule {
readonly attribute CSSStyleSheet? parentStyleSheet;
};
```
3. If the IDL starts with `[Exposed=Window]`, add the following to [`LibWeb/Bindings/WindowObjectHelper.h`](../../Userland/Libraries/LibWeb/Bindings/WindowObjectHelper.h):
Documentation: Add documentation for adding IDL files There are several steps involved, which are not at all obvious unless you already know them. So now they're written down. :^)
2021-10-03 17:32:01 -03:00
- `#include <LibWeb/Bindings/HTMLDetailsElementConstructor.h>` and
- `#include <LibWeb/Bindings/HTMLDetailsElementPrototype.h>` to the includes list.
- `ADD_WINDOW_OBJECT_INTERFACE(HTMLDetailsElement) \` to the macro at the bottom.
Everywhere: Rename WrapperGenerator to BindingsGenerator This code generator no longer creates JS wrappers for platform objects in the old sense, instead they're JS objects internally themselves. Most of what we generate now are prototypes - which can be seen as bindings for the internal C++ methods implementing getters, setters, and methods - as well as object constructors, i.e. bindings for the internal create_with_global_object() method. Also tweak the naming of various CMake glue code existing around this.
2022-09-21 14:22:16 -03:00
4. Add a `libweb_js_bindings(HTML/HTMLDetailsElement)` call to [`LibWeb/idl_files.cmake`](../../Userland/Libraries/LibWeb/idl_files.cmake)
Documentation: Add documentation for adding IDL files There are several steps involved, which are not at all obvious unless you already know them. So now they're written down. :^)
2021-10-03 17:32:01 -03:00
Documentation: Correct and update IDL documentation - Delete the part about removing `[Exposed=Window]` since that's not necessary and we may want that information there to generate the Window object. - Mention adding `#import`s. - Outline the requirements for the implementation class. - Mention the non-Event wrapper factories that need to know about certain types. I tend to refer to this document every time I add an IDL type so it's helpful if it's comprehensive.
2022-04-22 16:18:16 -03:00
5. Forward declare the generated classes in [`LibWeb/Forward.h`](../../Userland/Libraries/LibWeb/Forward.h):
Documentation: Add documentation for adding IDL files There are several steps involved, which are not at all obvious unless you already know them. So now they're written down. :^)
2021-10-03 17:32:01 -03:00
- `HTMLDetailsElement` in its namespace.
- `HTMLDetailsElementWrapper` in the `Web::Bindings` namespace.
Documentation: Correct and update IDL documentation - Delete the part about removing `[Exposed=Window]` since that's not necessary and we may want that information there to generate the Window object. - Mention adding `#import`s. - Outline the requirements for the implementation class. - Mention the non-Event wrapper factories that need to know about certain types. I tend to refer to this document every time I add an IDL type so it's helpful if it's comprehensive.
2022-04-22 16:18:16 -03:00
6. The C++ class equivalent of the IDL interface has a few requirements:
- It must inherit from `public RefCounted<HTMLDetailsElement>` and `public Bindings::Wrappable`
- It must have a public `using WrapperType = Bindings::HTMLDetailsElementWrapper;`
Everywhere: Rename WrapperGenerator to BindingsGenerator This code generator no longer creates JS wrappers for platform objects in the old sense, instead they're JS objects internally themselves. Most of what we generate now are prototypes - which can be seen as bindings for the internal C++ methods implementing getters, setters, and methods - as well as object constructors, i.e. bindings for the internal create_with_global_object() method. Also tweak the naming of various CMake glue code existing around this.
2022-09-21 14:22:16 -03:00
8. If your type isn't an Event or Element, you will need to add it to [`is_wrappable_type()`](../../Meta/Lagom/Tools/CodeGenerators/LibWeb/BindingsGenerator/IDLGenerators.cpp)
Documentation: Add missing step when creating a new IDL type If you use your new IDL class as a type in an IDL file without doing this, you'll get confusing error messages.
2022-08-11 13:46:13 -03:00
so that it can be accepted as an IDL parameter, attribute or return type.
Reference in a new issue Copy permalink